Update coding, contribution and moderation guides

config/nimdoc.cfg

@@ -129,11 +129,11 @@ doc.body_toc_group = """
   <div id="global-links">
     <ul class="simple-boot">
       <li><a href="manual.html">Manual</a></li>
+      <li><a href="style_guide.html">Style guide</a></li>
+      <li><a href="contributing.html">Contribution guide</a></li>
       <li><a href="lib.html">Standard library</a></li>
-      <li> <a href="$theindexhref">Index</a></li>
+      <li><a href="$theindexhref">Index</a></li>
       <li><a href="compiler/$theindexhref">Compiler docs</a></li>
-      <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
-      <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
     </ul>
   </div>
   <div id="searchInputDiv">

doc/docs.rst

@@ -34,5 +34,8 @@ The documentation consists of several documents:
   | The internal documentation describes how the compiler is implemented. Read
     this if you want to hack the compiler.
 
+- | `Language specification <spec.html>`_
+  | Description of the language specification purpose and structure.
+
 - | `Index <theindex.html>`_
-  | The generated index. **Index + (Ctrl+F) == Joy**
+  | The generated index.

doc/intern.rst

@@ -1,12 +1,10 @@
+.. include:: rstcommon.rst
+
 =========================================
     Internals of the |NimSkull| Compiler
 =========================================
 
-
-:Version: |nimversion|
-
 .. default-role:: code
-.. include:: rstcommon.rst
 .. contents::
 
   "Abstraction is layering ignorance on top of reality." -- Richard Gabriel
@@ -15,39 +13,32 @@
 Directory structure
 ===================
 
-The |NimSkull| project's directory structure is:
-
-============   ===================================================
-Path           Purpose
-============   ===================================================
-`bin`          generated binary files
-`build`        generated C code for the installation
-`compiler`     the |NimSkull| compiler itself; note that this
-               code has been translated from a bootstrapping
-               version written in Pascal, so the code is **not**
-               a poster child of good |NimSkull| code
-`config`       configuration files for |NimSkull|
-`dist`         additional packages for the distribution
-`doc`          the documentation; it is a bunch of
-               reStructuredText files
-`lib`          the |NimSkull| library
-`tests`        the tests for |NimSkull|, including the language
-               specification under `tests/lang`
-============   ===================================================
-
-
-Language Specification
-======================
-
-The official language specification is written as a growing set of tests within
-the `tests/lang` directory. Otherwise, the next best thing is the manual with
-the caveat that as any human language document that isn't executable it's often
-the source of language design flaws and features that don't compose well.
-
-In spirit the manual is correct, but it is superseded by the spec and as the
-spec grows and forces reconciliation of various design decisions the manual
-may diverge further. Of course, we want to keep it upto date and attempt to do
-so, if you find issues please help us fix it.
+The |nimskull| project's directory structure is:
+
+- ``bin/``, ``build/`` - these directories are empty, but are used when |nimskull|
+  is built.
+- ``compiler/`` - the compiler source code. Also includes nimfix, and
+  plugins within ``compiler/nimfix`` and ``compiler/plugins`` respectively.
+- ``nimsuggest`` - the nimsuggest tool.
+- ``config/`` - the configuration for the compiler and documentation
+  generator.
+- ``dist`` - additional packages for distribution
+- ``doc/`` - the documentation files in reStructuredText format.
+- ``lib/`` - the standard library, including:
+    - ``pure/`` - modules in the standard library written in pure
+      |nimskull|.
+    - ``impure/`` - modules in the standard library written in pure
+    |nimskull| with dependencies written in other languages.
+    - ``wrappers/`` - modules that wrap dependencies written in other
+      languages.
+- ``tests/`` - contains categorized tests for the compiler and standard
+  library.
+  - ``tests/lang`` - tests containing language specification
+- ``tools/`` - the tools including ``koch``, ``niminst`` and ``nimweb``
+  (mostly invoked via ``koch``).
+- ``tools/koch/koch.nim`` - the tool used to bootstrap |nimskull|, generate C
+  sources, build the website, and generate the documentation.
+- ``koch.py`` - the script to bootstrap and launch ``koch.nim``.
 
 
 Bootstrapping the compiler

doc/moderation.rst

@@ -0,0 +1,70 @@
+==========
+Moderation
+==========
+
+.. default-role:: code
+.. include:: rstcommon.rst
+
+.. contents::
+
+This document covers main rules that concern moderation of the various
+nimskull projects and public spaces. This is an initial version, and it is
+mostly concerned with establishing rules of interactions when it comes to
+accepting and reviewing pull requests, managing github labels, explaining
+current project goals and so on.
+
+Helping newcomers
+=================
+
+  "The best thing you can do, as a knowledge community member, is to enable
+  others to contribute. Small effort on your end could go a long way when
+  it comes to helping others - there is no shortage of bright and motivated
+  people who are willing contribute, but not everyone has time to figure
+  out what needs to be done from scratch"
+
+
+Managing github labels
+======================
+
+In addition to general "bug", "documentation", "enhancement" and similar
+labels there are quite a few that were added specifically to distinguish
+different actions that need to be taken in order to progress with a pull
+request or issue. They must be handed out with care, and each label
+assignment needs to be elaborated.
+
+- "Good first issue" - if person assigning such label decided this issue is
+  a good fit for a newcomer (that is - person unfamillar with a codebase),
+  they should elaborate on how specifically it can be solved. More often
+  that not definition of "simple" varies between people.
+- "spec needed" - pull request and issue requires a thorough specification
+  of the involved parts.
+
+Code reviews
+============
+
+When reviewing code it is highly recommended to check whether it complies
+with official style guide and point out mismatches.
+
+Examining the changes
+---------------------
+
+1. Whenever possible, use GitHub's new 'Suggested change' in code reviews, which
+   saves time explaining the change or applying it
+
+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:: cmd
+
+      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
+   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`