Skip to content

Commit 574bacc

Browse files
w0rpw0rp
committed
Add development documentation, and .github files
1 parent b1ffbe3 commit 574bacc

File tree

4 files changed

+272
-4
lines changed

4 files changed

+272
-4
lines changed

‎.github/CONTRIBUTING.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## Guidelines
2+
3+
Have fun, and work on whatever floats your boat. Take It Easy :tm:.
4+
5+
For help with contributing to Neural, see `:help neural-dev` in Vim, or view the
6+
help file online [here](/doc/neural-development.txt).
7+
8+
## Creating Issues
9+
10+
Before creating any issues, please look through the current list of issues and
11+
pull requests, and ensure that the issue hasn't already been reported. If an
12+
issue has already been reported, but you have some new insight, please add
13+
a comment to the existing issue.
14+
15+
Please try and describe any issues reported with as much detail as you can
16+
provide about your Vim version, the linter you were trying to run, your
17+
operating system, or any other information you think might be helpful.
18+
19+
Please describe your issue in clear, grammatically correct, and easy to
20+
understand English. You are more likely to see an issue resolved if others
21+
can understand you.

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!--
2+
Before creating a pull request, do the following.
3+
4+
* Read the Contributing guide linked above first.
5+
* Read the documentation that comes with Neural with `:help neural-dev`.
6+
7+
Have fun!
8+
-->
9+
10+
Where are the tests? Have you added tests? Have you updated the tests? Read the
11+
comment above and the documentation referenced in it first. Write tests!
12+
13+
Seriously, read `:help neural-dev` and write tests.

‎doc/neural-development.txt

Lines changed: 237 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,250 @@
1-
WIP
1+
*neural-development.txt* For Vim and Neovim.
2+
*neural-dev*
3+
*neural-development*
24

3-
Make sure all required Python versions for testing are installed.
5+
Neural Development Documentation
46

7+
===============================================================================
8+
CONTENTS *neural-development-contents*
9+
10+
1. Introduction.........................|neural-development-introduction|
11+
2. Design Goals.........................|neural-design-goals|
12+
3. Coding Standards.....................|neural-coding-standards|
13+
4. Development Environment..............|neural-development-environment|
14+
5. Testing Neural.......................|neural-development-tests|
15+
6. Contributing.........................|neural-development-contributing|
16+
6.1. Preparing a Release..............|neural-development-release|
17+
18+
19+
===============================================================================
20+
1. Introduction *neural-development-introduction*
21+
22+
This document contains helpful information for Neural developers, including
23+
design goals, information on how to run the tests, coding standards, and so
24+
on. You should read this document if you want to get involved with Neural
25+
development.
26+
27+
28+
===============================================================================
29+
2. Design Goals *neural-design-goals*
30+
31+
This section lists design goals for Neural, in no particular order. They are as
32+
follows.
33+
34+
Neural code should be mostly VimL to maintain compatibility with Vim,
35+
in some part Lua to permit better functionality for Neovim, and Python using
36+
absolutely zero dependencies. Using Python without anything but first party
37+
library functions allows Neural to run if it can find any system-installed
38+
Python of a reasonable version, with no further installation steps required.
39+
40+
Neural should run without needing any other Vim plugins to be installed, to
41+
keep installation simple. Neural can integrate with other plugins for more
42+
advanced functionality, non-essential functionality, or improving on basic
43+
first party functionality.
44+
45+
Neural should be free of breaking changes to the public API, which is
46+
comprised of documented functions and options, until a major version is
47+
planned. Breaking changes should be preceded by a deprecation phase complete
48+
with warnings. Changes required for security may be an exception.
49+
50+
Neural supports Vim 8 and above, and Neovim 0.8.0 or newer. Vim 8 is the
51+
earliest version of Vim which supports |job|, |timer|, |closure|, and |lambda|
52+
features. Neovim 0.8.0 is the earliest version to support moderately good UI
53+
features users now expect for a plugin like Neural.
54+
55+
Just about everything should be documented and covered with tests.
56+
57+
By and large, people shouldn't pay for the functionality they don't use. Care
58+
should be taken when adding new features, so supporting new features doesn't
59+
degrade the general performance of anything Neural does.
60+
61+
62+
===============================================================================
63+
3. Coding Standards *neural-coding-standards*
64+
65+
The following general coding standards should be adhered to for Vim code.
66+
67+
* Check your Vim code with `Vint` and do everything it says. ALE will check
68+
your Vim code with Vint automatically. See: https://github.com/Kuniwak/vint
69+
* Try to write descriptive and concise names for variables and functions.
70+
Names shouldn't be too short or too long. Think about others reading your
71+
code later on.
72+
* Use `snake_case` names for variables and arguments, and `PascalCase` names
73+
for functions. Prefix every variable name with its scope. (`l:`, `g:`, etc.)
74+
* Try to keep lines no longer than 80 characters, but this isn't an absolute
75+
requirement.
76+
* Use 4 spaces for every level of indentation in Vim code.
77+
* Add a blank line before every `function`, `if`, `for`, `while`, or `return`,
78+
which doesn't start a new level of indentation. This makes the logic in
79+
your code easier to follow.
80+
* End every file with a trailing newline character, but not with extra blank
81+
lines. Remove trailing whitespace from the ends of lines.
82+
* Write the full names of commands instead of abbreviations. For example, write
83+
`function` instead of `func`, and `endif` instead of `end`.
84+
* Write functions with `!`, so files can be reloaded. Use the |abort| keyword
85+
for all functions, so functions exit on the first error.
86+
* Make sure to credit yourself in files you have authored with `Author:`
87+
and `Description:` comments.
88+
89+
The following general coding standards should be adhered to for Python code.
90+
91+
* Make sure to run `flake8` on code, and adhere to typical PEP8 coding
92+
standards.
93+
* Make sure to run `pyright` on code, and ensure your code passes type
94+
checking rules.
95+
* Make sure to run `isort` on code to keep imports sorted.
96+
* Maintain near 100% test coverage of Python code with `unittest` tests.
97+
* You may only use first party Python libraries.
98+
* Try to make sure code will run with whatever version of Python Debian stable
99+
runs.
100+
101+
NOTE: We do not currently offer guidelines for Lua code.
102+
103+
Apply the following guidelines when writing Vader test files.
104+
105+
* Use 2 spaces for Vader test files, instead of the 4 spaces for Vim files.
106+
* If you write `Before` and `After` blocks, you should typically write them at
107+
the top of the file, so they run for all tests. There may be some tests
108+
where it make sense to modify the `Before` and `After` code part of the way
109+
through the file.
110+
* If you modify any settings or global variables, reset them in `After`
111+
blocks. The Vader `Save` and `Restore` commands can be useful for this
112+
purpose.
113+
* Just write `Execute` blocks for Vader tests, and don't bother writing `Then`
114+
blocks. `Then` blocks execute after `After` blocks in older versions, and
115+
that can be confusing.
116+
117+
Apply the following rules when writing Bash scripts.
118+
119+
* Run `shellcheck`, (ALE will run it) and do everything it says.
120+
See: https://github.com/koalaman/shellcheck
121+
* Try to write scripts so they will run on Linux, BSD, or Mac OSX.
122+
123+
124+
===============================================================================
125+
4. Development Environment *neural-development-environment*
126+
127+
You can run `tox` without Docker if you install the required Python versions.
5128
Neural tests against Python 3.7 and Python 3.10.
6129

7130
Run the following: >
8131
python -m pip install --user tox==4.4.5
9132
python -m tox
10133
<
11-
12134
To get the same configuration in your editor, run `./install-python-env.sh`.
13-
ALE should pick up on how to run `ruff` and `pyright` automatically.
135+
ALE should pick up on how to run `flake8` and `pyright` automatically, but you
136+
may wish to configure ALE to run only those linters. You can configure ALE
137+
to fix the Python files with `isort`. Apply the following settings: >
138+
139+
if expand('%:p') =~# 'neural'
140+
let b:ale_linters = ['flake8', 'pyright']
141+
let b:ale_fixers = ['isort']
142+
endif
143+
<
144+
145+
===============================================================================
146+
5. Testing Neural *neural-development-tests* *neural-tests*
147+
148+
Neural is tested with a suite of tests executed via GitHub Actions.
149+
Neural runs tests with the following versions of Vim.
150+
151+
1. Vim 8.0.0027 on Linux.
152+
2. Vim 9.0.0297 on Linux.
153+
3. NeoVim 0.8.0 on Linux.
154+
155+
If you are developing Neural code on Linux, Mac OSX, or BSD, you can run
156+
Neural's tests by installing Docker and running the `run-tests` script. Follow
157+
the instructions on the Docker site for installing Docker.
158+
See: https://docs.docker.com/install/
159+
160+
NOTE: Don't forget to add your user to the `docker` group on Linux, or Docker
161+
just won't work. See: https://docs.docker.com/install/linux/linux-postinstall/
162+
163+
If you run simply `./run-tests` from the Neural repository root directory, the
164+
latest Docker image for tests will be downloaded if needed, and the script
165+
will run all of the tests in Vader, Vint checks, `tox`, and several Bash
166+
scripts for finding extra issues. Run `./run-tests --help` to see all of the
167+
options the script supports. The script supports selecting particular test
168+
files.
169+
170+
Once you get used to dealing with Vim and Neovim compatibility issues, you
171+
probably want to use `./run-tests --fast -q` for running tests with only the
172+
fastest available Vim version, and with success messages from tests
173+
suppressed.
174+
175+
Generally write tests for any changes you make.
176+
177+
Look at existing tests in the codebase for examples of how to write tests.
178+
Refer to the Vader documentation for general information on how to write Vader
179+
tests: https://github.com/junegunn/vader.vim
180+
181+
182+
===============================================================================
183+
6. Contributing *neural-development-contributing*
184+
185+
All integration of new code into Neural is done through GitHub pull requests.
186+
Using that tool streamlines the process and minimizes the time and effort
187+
required to e.g. ensure test suites are run for every change.
188+
189+
As for any project hosted by GitHub, the choice of platform demands every
190+
contributor to take care to setup an account and configure it accordingly.
191+
192+
Due to details of our process, a difference to many other GitHub hosted
193+
projects is that contributors who wish to keep the author fields for their
194+
commits unaltered need to configure a public email address in their account
195+
and profile settings. See: https://docs.github.com/en/account-and-profile/
196+
197+
Unless configuring GitHub to expose contact details, commits will be rewritten
198+
to appear by `USERNAME <[email protected]>` .
199+
200+
201+
-------------------------------------------------------------------------------
202+
6.1 Preparing a Release *neural-development-release*
203+
204+
Neural offers release packages through GitHub, for two reasons:
205+
206+
1. Some users like to target specific release versions rather than simply
207+
installing the plugin from `master`. This includes users who create Linux
208+
distribution specific packages from GitHub releases.
209+
2. The releases provide a nice way to get an overview of what has changed in
210+
Neural over time.
211+
212+
Neural has no fixed release schedule. Release versions are created whenever
213+
the Neural developers feel the need to create one. Neural release versions
214+
follow the typical Semantic Versioning scheme. See: https://semver.org/
215+
216+
If there are ever to be any breaking changes made for Neural, there should
217+
first come a minor version release for Neural documenting all of the coming
218+
breaking changes to Neural. It should be described how users can prepare for a
219+
breaking change that is coming before it is done. At the time of writing,
220+
Neural lives as version 0.x.x, and as such breaking changes may be more
221+
common.
222+
223+
To create a release for Neural, you will need sufficient permissions in GitHub.
224+
Once you do, follow these steps.
225+
226+
1. Create a new release draft, or edit an existing one. It helps to craft
227+
drafts ahead of time and write the last commit ID checked for release notes
228+
on the last update to a draft.
229+
See the releases page: https://github.com/dense-analysis/neural/releases
230+
2. Examine `git log` and read changes made between the last ID checked, or the
231+
git tag of the previous release, and the current commit in `master`.
232+
3. Write updates in separate sections (except where empty) for:
233+
3.a. New Features
234+
3.b. Bugs Fixed
235+
4. Commit the changes after `./run-tests --fast -q` passes.
236+
5. Tag the release with `git tag vA.B.C`, replacing `A`, `B`, and `C` with the
237+
version numbers. See `git tag --list` for examples.
238+
6. Run `git push` and `git push --tags` to push the commit and the tag.
239+
7. Edit the release draft in GitHub, select the tag you just pushed, and
240+
publish the draft.
241+
8. If you're creating a new major or minor version: `git checkout -b vA.B.x`,
242+
replacing `A` and `B` with the major and minor versions. `git push` the new
243+
branch, and the GitHub branch protection settings should automatically
244+
apply to the new release branch.
245+
9. You have already completed the last step.
14246

247+
Have fun creating Neural releases. Use your head, or Neural in place of it.
15248

16249
===============================================================================
17250
vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:

‎run-tests

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,7 @@ while [ $# -ne 0 ]; do
131131
echo ' --linters-only Run only Vint and custom checks'
132132
echo ' --python-only Run only Python checks'
133133
echo ' --fast Run only the fastest Vim and the rest'
134+
echo ' --no-docker Run test scripts on host, except for Vim'
134135
echo ' --help Show this help text'
135136
echo ' -- Stop parsing options after this'
136137
exit 0

0 commit comments

Comments
 (0)