diff options
Diffstat (limited to 'doc/contributing.md')
| -rw-r--r-- | doc/contributing.md | 46 |
1 files changed, 22 insertions, 24 deletions
diff --git a/doc/contributing.md b/doc/contributing.md index 83ca85663..420c1438e 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -11,7 +11,7 @@ Contributing Contributing happens via "Pull requests" (PR) on GitHub. Every PR needs to be reviewed before it can be merged and the Continuous Integration should be green. The title of a PR should contain a brief description. If it fixes an issue, -in addition to the number of the issue, the title should also contain a description +in addition to the number of the issue, the title should also contain a description of the issue. The PR has to be approved by two core developers or by Araq. @@ -137,9 +137,9 @@ You can run the tests with which will run a good subset of tests. Some tests may fail. If you only want to see the output of failing tests, go for -```cmd + ```cmd ./koch tests --failing all -``` + ``` You can also run only a single category of tests. A category is a subdirectory in the ``tests/`` directory. There are a couple of special categories; for a @@ -198,7 +198,7 @@ tell you if any new tests passed/failed. Deprecation =========== -Backwards compatibility is important. When renaming types, procedures, etc. the old name +Backwards compatibility is important. When renaming types, procedures, etc. the old name must be marked as deprecated using the `deprecated` pragma: ```nim @@ -314,14 +314,14 @@ To avoid accidental highlighting follow this rule in ``*.nim`` files: programming languages, including identifiers, in ``*.nim`` files. For languages other than Nim add a role after final backtick, - e.g. for C++ inline highlighting:: + e.g. for C++ inline highlighting: - `#include <stdio.h>`:cpp: + `#include <stdio.h>`:cpp: For a currently unsupported language add the `:code:` role, - like for SQL in this example:: + like for SQL in this example: - `SELECT * FROM <table_name>;`:code: + `SELECT * FROM <table_name>;`:code: Highlight shell commands by ``:cmd:`` role; for command line options use ``:option:`` role, e.g.: \`--docInternal\`:option:. @@ -335,17 +335,17 @@ To avoid accidental highlighting follow this rule in ``*.nim`` files: ``\`` and a final \` would get escaped) .. Note:: ``*.rst`` files have ``:literal:`` as their default role. - So for them the rule above is only applicable if the ``:nim:`` role - is set up manually as the default \[*]:: + So for them the rule above is only applicable if the ``:nim:`` role + is set up manually as the default [^1]: - .. role:: nim(code) - :language: nim - .. default-role:: nim + .. role:: nim(code) + :language: nim + .. default-role:: nim - The first 2 lines are for other RST implementations, - including Github one. + The first 2 lines are for other RST implementations, + including Github one. - \[*] this is fulfilled when ``doc/rstcommon.rst`` is included. + [^1]: this is fulfilled when ``doc/rstcommon.rst`` is included. Best practices ============== @@ -489,9 +489,9 @@ General commit rules git diff --check --cached || exit $? ``` 5. Describe your commit and use your common sense. - Example commit message:: + Example commit message: - Fixes #123; refs #124 + Fixes #123; refs #124 indicates that issue ``#123`` is completely fixed (GitHub may automatically close it when the PR is committed), whereas issue ``#124`` is referenced @@ -513,7 +513,7 @@ General commit rules https://github.com/nim-lang/Nim/pull/9356 8. Do not mix pure formatting changes (e.g. whitespace changes, nimpretty) or - automated changes (e.g. nimfix) with other code changes: these should be in + automated changes with other code changes: these should be in separate commits (and the merge on GitHub should not squash these into 1). @@ -581,11 +581,9 @@ Code reviews 3. In addition, you can view GitHub-like diffs locally to identify what was changed within a code block using `diff-highlight`:cmd: or `diff-so-fancy`:cmd:, e.g.: - :: - - # put this in ~/.gitconfig: - [core] - pager = "diff-so-fancy | less -R" # or: use: `diff-highlight` + # put this in ~/.gitconfig: + [core] + pager = "diff-so-fancy | less -R" # or: use: `diff-highlight` |