diff options
| -rw-r--r-- | doc/contributing.rst | 36 | ||||
| -rw-r--r-- | doc/gc.rst | 32 | ||||
| -rw-r--r-- | readme.md | 20 | ||||
| -rw-r--r-- | security.md | 4 |
4 files changed, 46 insertions, 46 deletions
diff --git a/doc/contributing.rst b/doc/contributing.rst index 15017cd84..f570336e2 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -49,7 +49,7 @@ which only gets executed when the tester is building the file. Each test should be in a separate ``block:`` statement, such that each has its own scope. Use boolean conditions and ``doAssert`` for the -testing by itself, don't rely on echo statements or similar; in particular avoid +testing by itself, don't rely on echo statements or similar; in particular, avoid things like `echo "done"`. Sample test: @@ -69,7 +69,7 @@ Sample test: # doAssert with `not` can now be done as follows: doAssert not (1 == 2) -Always refer to a github issue using the following exact syntax: `bug #1234` as shown +Always refer to a GitHub issue using the following exact syntax: `bug #1234` as shown above, so that it's consistent and easier to search or for tooling. Some browser extensions (e.g. https://github.com/sindresorhus/refined-github) will even turn those in clickable links when it works. @@ -100,7 +100,7 @@ Possible keys are: For a full spec, see here: ``testament/specs.nim`` -An example for a test: +An example of a test: .. code-block:: nim @@ -162,7 +162,7 @@ Comparing tests Test failures can be grepped using ``Failure:``. -The tester can compare two test runs. First, you need to create the +The tester can compare two test runs. First, you need to create a reference test. You'll also need to the commit id, because that's what the tester needs to know in order to compare the two. @@ -344,7 +344,7 @@ which for which ``nim doc`` ignores ``-d:release``). .. _delegate_printing: Delegate printing to caller: return ``string`` instead of calling ``echo`` -rationale: it's more flexible (e.g. allows caller to call custom printing, +rationale: it's more flexible (e.g. allows the caller to call custom printing, including prepending location info, writing to log files, etc). .. code-block:: nim @@ -364,7 +364,7 @@ unless stack allocation is needed (e.g. for efficiency). .. _use_doAssert_not_echo: Tests (including in testament) should always prefer assertions over ``echo``, except when that's not possible. It's more precise, easier for readers and -maintaners to where expected values refer to. See for example +maintainers to where expected values refer to. See for example https://github.com/nim-lang/Nim/pull/9335 and https://forum.nim-lang.org/t/4089 .. code-block:: nim @@ -386,7 +386,7 @@ General commit rules stable releases" and the tag ``[backport:$VERSION]`` for backporting to the given $VERSION. -2. If you introduce changes which affect backwards compatibility, +2. If you introduce changes which affect backward compatibility, make breaking changes, or have PR which is tagged as ``[feature]``, the changes should be mentioned in `the changelog <https://github.com/nim-lang/Nim/blob/devel/changelog.md>`_. @@ -404,7 +404,7 @@ General commit rules 4. Changes should not introduce any trailing whitespace. Always check your changes for whitespace errors using ``git diff --check`` - or add following ``pre-commit`` hook: + or add the following ``pre-commit`` hook: .. code-block:: sh @@ -416,7 +416,7 @@ General commit rules ``Fixes #123; refs #124`` - indicates that issue ``#123`` is completely fixed (github may automatically + indicates that issue ``#123`` is completely fixed (GitHub may automatically close it when the PR is committed), wheres issue ``#124`` is referenced (e.g.: partially fixed) and won't close the issue when committed. @@ -431,7 +431,7 @@ General commit rules 7. 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 - separate commits (and the merge on github should not squash these into 1). + separate commits (and the merge on GitHub should not squash these into 1). Continuous Integration (CI) @@ -444,9 +444,9 @@ Continuous Integration (CI) <https://www.appveyor.com/docs/how-to/filtering-commits/#skip-directive-in-commit-message>`_ and `Travis <https://docs.travis-ci.com/user/customizing-the-build/#skipping-a-build>`_. -2. Consider enabling CI (azure, github actions and builds.sr.ht) in your own Nim fork, and +2. Consider enabling CI (azure, GitHub actions and builds.sr.ht) in your own Nim fork, and waiting for CI to be green in that fork (fixing bugs as needed) before - opening your PR in original Nim repo, so as to reduce CI congestion. Same + opening your PR in the original Nim repo, so as to reduce CI congestion. Same applies for updates on a PR: you can test commits on a separate private branch before updating the main PR. @@ -463,21 +463,21 @@ Debugging CI failures, flaky tests, etc * Azure: if on your own fork, it's possible from inside azure console (e.g. `dev.azure.com/username/username/_build/results?buildId=1430&view=results`) via `rerun failed jobs` on top. - If either on you own fork or in Nim repo, it's possible from inside github UI + If either on you own fork or in Nim repo, it's possible from inside GitHub UI under checks tab, see https://github.com/timotheecour/Nim/issues/211#issuecomment-629751569 - * github actions: under "Checks" tab, click "Re-run jobs" in the right. + * GitHub actions: under "Checks" tab, click "Re-run jobs" in the right. * builds.sr.ht: create a sourcehut account so you can restart a PR job as illustrated Code reviews ------------ -1. Whenever possible, use github's new 'Suggested change' in code reviews, which +1. Whenever possible, use GitHub's new 'Suggested change' in code reviews, which saves time explaining the change or applying it; see also https://forum.nim-lang.org/t/4317 -2. When reviewing large diffs that may involve code moving around, github's interface - doesn't help much as it doesn't highlight moves. Instead you can use something +2. When reviewing large diffs that may involve code moving around, GitHub's interface + doesn't help much as it doesn't highlight moves. Instead, you can use something like this, see visual results `here <https://github.com/nim-lang/Nim/pull/10431#issuecomment-456968196>`_: .. code-block:: sh @@ -485,7 +485,7 @@ Code reviews git fetch origin pull/10431/head && git checkout FETCH_HEAD git diff --color-moved-ws=allow-indentation-change --color-moved=blocks HEAD^ -3. In addition, you can view github-like diffs locally to identify what was changed +3. In addition, you can view GitHub-like diffs locally to identify what was changed within a code block using `diff-highlight` or `diff-so-fancy`, e.g.: .. code-block:: sh diff --git a/doc/gc.rst b/doc/gc.rst index 84a1338c3..23c4f64cf 100644 --- a/doc/gc.rst +++ b/doc/gc.rst @@ -26,8 +26,8 @@ To choose the memory management strategy use the ``--gc:`` switch. - ``--gc:refc``. This is the default GC. It's a deferred reference counting based garbage collector - with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread local. -- ``--gc:markAndSweep``. Simple Mark-And-Sweep based garbage collector. Heaps are thread local. + with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread-local. +- ``--gc:markAndSweep``. Simple Mark-And-Sweep based garbage collector. Heaps are thread-local. - ``--gc:boehm``. Boehm based garbage collector, it offers a shared heap. - ``--gc:go``. Go's garbage collector, useful for interoperability with Go. Offers a shared heap. - ``--gc:arc``. Plain reference counting with @@ -36,10 +36,10 @@ To choose the memory management strategy use the ``--gc:`` switch. cause memory leaks, beware. - ``--gc:orc``. Same as ``--gc:arc`` but adds a cycle collector based on "trial deletion". - Unfortunately that makes its performance profile hard to reason about so it is less - useful for hard realtime systems. + Unfortunately, that makes its performance profile hard to reason about so it is less + useful for hard real-time systems. -- ``--gc:none``. No memory management strategy nor garbage collector. Allocated memory is +- ``--gc:none``. No memory management strategy nor a garbage collector. Allocated memory is simply never freed. You should use ``--gc:arc`` instead. @@ -71,10 +71,10 @@ The cycle collector can be en-/disabled independently from the other parts of the garbage collector with ``GC_enableMarkAndSweep`` and ``GC_disableMarkAndSweep``. -Soft realtime support +Soft real-time support --------------------- -To enable realtime support, the symbol `useRealtimeGC`:idx: needs to be +To enable real-time support, the symbol `useRealtimeGC`:idx: needs to be defined via ``--define:useRealtimeGC`` (you can put this into your config file as well). With this switch the garbage collector supports the following operations: @@ -85,7 +85,7 @@ With this switch the garbage collector supports the following operations: The unit of the parameters ``maxPauseInUs`` and ``us`` is microseconds. -These two procs are the two modus operandi of the realtime garbage collector: +These two procs are the two modus operandi of the real-time garbage collector: (1) GC_SetMaxPause Mode @@ -98,7 +98,7 @@ These two procs are the two modus operandi of the realtime garbage collector: (2) GC_step Mode This allows the garbage collector to perform some work for up to ``us`` time. - This is useful to call in a main loop to ensure the garbage collector can do its work. + This is useful to call in the main loop to ensure the garbage collector can do its work. To bind all garbage collector activity to a ``GC_step`` call, deactivate the garbage collector with ``GC_disable`` at program startup. If ``strongAdvice`` is set to ``true``, @@ -106,13 +106,13 @@ These two procs are the two modus operandi of the realtime garbage collector: Otherwise, the garbage collector may decide not to do anything, if there is not much garbage to collect. You may also specify the current stack size via ``stackSize`` parameter. - It can improve performance, when you know that there are no unique Nim - references below certain point on the stack. Make sure the size you specify - is greater than the potential worst case size. + It can improve performance when you know that there are no unique Nim + references below a certain point on the stack. Make sure the size you specify + is greater than the potential worst-case size. -These procs provide a "best effort" realtime guarantee; in particular the +These procs provide a "best effort" real-time guarantee; in particular the cycle collector is not aware of deadlines. Deactivate it to get more -predictable realtime behaviour. Tests show that a 1ms max pause +predictable real-time behaviour. Tests show that a 1ms max pause time will be met in almost all cases on modern CPUs (with the cycle collector disabled). @@ -120,14 +120,14 @@ disabled). Time measurement with garbage collectors ---------------------------------------- -The garbage collectors's way of measuring time uses +The garbage collectors' way of measuring time uses (see ``lib/system/timers.nim`` for the implementation): 1) ``QueryPerformanceCounter`` and ``QueryPerformanceFrequency`` on Windows. 2) ``mach_absolute_time`` on Mac OS X. 3) ``gettimeofday`` on Posix systems. -As such it supports a resolution of nanoseconds internally; however the API +As such it supports a resolution of nanoseconds internally; however, the API uses microseconds for convenience. Define the symbol ``reportMissedDeadlines`` to make the diff --git a/readme.md b/readme.md index 8fcf4d2bb..bfd153143 100644 --- a/readme.md +++ b/readme.md @@ -2,7 +2,7 @@ [](https://dev.azure.com/nim-lang/Nim/_build/latest?definitionId=1&branchName=devel) -This repository contains the Nim compiler, Nim's stdlib, tools and documentation. +This repository contains the Nim compiler, Nim's stdlib, tools, and documentation. For more information about Nim, including downloads and documentation for the latest release, check out [Nim's website][nim-site] or [bleeding edge docs](https://nim-lang.github.io/Nim/). @@ -37,7 +37,7 @@ architecture combinations: * Linux (most, if not all, distributions) - x86, x86_64, ppc64 and armv6l * Mac OS X (10.04 or greater) - x86, x86_64 and ppc64 -More platforms are supported, however they are not tested regularly and they +More platforms are supported, however, they are not tested regularly and they may not be as stable as the above-listed platforms. Compiling the Nim compiler is quite straightforward if you follow these steps: @@ -60,10 +60,10 @@ Next, to build from source you will need: * [MinGW32.7z](https://nim-lang.org/download/mingw32.7z) * [MinGW64.7z](https://nim-lang.org/download/mingw64.7z) -**Windows Note: Cygwin and similar posix runtime environments are not supported.** +**Windows Note: Cygwin and similar POSIX runtime environments are not supported.** Then, if you are on a \*nix system or Windows, the following steps should compile -Nim from source using ``gcc``, ``git`` and the ``koch`` build tool. +Nim from source using ``gcc``, ``git``, and the ``koch`` build tool. **Note: The following commands are for the development version of the compiler.** For most users, installing the latest stable version is enough. Check out @@ -72,14 +72,14 @@ the installation instructions on the website to do so: https://nim-lang.org/inst For package maintainers: see [packaging guidelines](https://nim-lang.github.io/Nim/packaging.html). -First get Nim from github: +First, get Nim from github: ``` git clone https://github.com/nim-lang/Nim.git cd Nim ``` -Next run the appropriate build shell script for your platform: +Next, run the appropriate build shell script for your platform: * `build_all.sh` (Linux, Mac) * `build_all.bat` (Windows) @@ -88,7 +88,7 @@ Windows requires a number of other dependencies that you may need to install inc PCRE and OpenSSL. Nim hosts a zip package containing known working versions of the required DLLs [here](https://nim-lang.org/download/dlls.zip). -Finally, once you have finished the build steps (on Windows, Mac or Linux) you +Finally, once you have finished the build steps (on Windows, Mac, or Linux) you should add the ``bin`` directory to your PATH. See also [rebuilding the compiler](doc/intern.rst#rebuilding-the-compiler). @@ -140,11 +140,11 @@ you should familiarize yourself with the following repository structure: * ``pure/`` - modules in the standard library written in pure Nim. * ``impure/`` - modules in the standard library written in pure Nim with dependencies written in other languages. - * ``wrappers/`` - modules which wrap dependencies written in other languages. + * ``wrappers/`` - modules that wrap dependencies written in other languages. * ``tests/`` - contains categorized tests for the compiler and standard library. * ``tools/`` - the tools including ``niminst`` and ``nimweb`` (mostly invoked via ``koch``). -* ``koch.nim`` - tool used to bootstrap Nim, generate C sources, build the website, +* ``koch.nim`` - the tool used to bootstrap Nim, generate C sources, build the website, and generate the documentation. If you are not familiar with making a pull request using GitHub and/or git, please @@ -198,7 +198,7 @@ You can also see a list of all our sponsors/backers from various payment service ## License The compiler and the standard library are licensed under the MIT license, except -for some modules which explicitly state otherwise. As a result you may use any +for some modules which explicitly state otherwise. As a result, you may use any compatible license (essentially any license) for your own programs developed with Nim. You are explicitly permitted to develop commercial applications using Nim. diff --git a/security.md b/security.md index f1eaf3290..e8d31b1b9 100644 --- a/security.md +++ b/security.md @@ -12,6 +12,6 @@ We do not backport security fixes to older releases. Please do not report vulnerabilities via GitHub issues. -If you have discovered a vulnerability, it is the best to notify us about it via -security@nim-lang.org in order to setup a meeting where we can discuss the next +If you have discovered a vulnerability, it is best to notify us about it via +security@nim-lang.org in order to set up a meeting where we can discuss the next steps. |