update contributing.rst and added codeowners.rst

2 files changed, 83 insertions, 19 deletions

diff --git a/doc/codeowners.rst b/doc/codeowners.rst
new file mode 100644
index 000000000..19f5d6ee1
--- /dev/null
+++ b/doc/codeowners.rst
@@ -0,0 +1,64 @@
+===========
+Code owners
+===========
+
+
+Subsystems and code owners
+--------------------------
+
+*Note*: This list is incomplete, in doubt dom96 is responsible for the standard
+library, araq is responsible for the compiler.
+
+
+Compiler
+~~~~~~~~
+
+======================         ======================================================
+subsystem                      owner(s)
+======================         ======================================================
+Parsing, Lexing                araq
+Renderer                       cooldome, araq
+Order of passes                cooldome
+Semantic Checking              araq
+Virtual machine                jangko, cooldome, GULPF, araq
+Sempass2: effects tracking     araq
+type system, concepts          zahary
+transf                         araq
+semfold constant folding       araq
+template instantiation         zahary, araq
+term rewriting macros          araq
+closure interators             yglukhov, araq
+lambda lifting                 yglukhov, araq
+c, cpp codegen                 lemonboy, araq
+js codegen                     yglukhov, lemonboy
+alias analysis                 araq
+dfa, writetracking             araq
+parallel, multithreading       araq
+incremental                    araq
+sizeof computations            krux02
+======================         ======================================================
+
+
+
+Standard library
+~~~~~~~~~~~~~~~~
+
+======================    ======================================================
+subsystem                 owner(s)
+======================    ======================================================
+async                     dom96
+strutils                  araq
+sequtils                  dom96, araq
+times                     GULPF
+os, ospaths               dom96, araq
+re                        araq
+nre                       flaviu
+math                      krux02
+io                        dom96
+garbage collector         araq
+Go garbage collector      stefantalpalaru
+coroutines                Rokas Kupstys
+collections               GULPF
+parseopt                  araq
+json                      dom96
+======================    ======================================================
diff --git a/doc/contributing.rst b/doc/contributing.rst
index 814b1af28..72c3ed807 100644
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@@ -1,3 +1,16 @@
+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 PR has to be approved (and is often merged too) by one "code owner", either
+by the code owner who is responsible for the subsystem the PR belongs to or by
+two core developers or by Araq.
+
+See `codeowners <codeowners.html>`_ for more details.
+
+
 Writing tests
 =============
 
@@ -6,7 +19,7 @@ There are 3 types of tests:
 1. ``runnableExamples`` documentation comment tests, ran by ``nim doc mymod.nim``
    These end up in documentation and ensure documentation stays in sync with code.
 
-2. tests in `when isMainModule:` block, ran by ``nim c mymod.nim``
+2. tests in ``when isMainModule:`` block, ran by ``nim c mymod.nim``
    ``nimble test`` also typially runs these in external nimble packages.
 
 3. testament tests, eg: tests/stdlib/tospaths.nim (only used for Nim repo).
@@ -146,18 +159,8 @@ tell you if any new tests passed/failed.
 Deprecation
 ===========
 
-Backward compatibility is important, so if you are renaming a routine
-(proc/template/macro/iterator) or a type you can use:
-
-.. code-block:: nim
-
-  {.deprecated: [oldName: new_name].}
-
-This form may enable future automated tooling to upgrade code (eg nimfix, which
-was used in the past for nimrod -> nim migration).
-
-Besides pure renamings (eg when parameters change) you can mark a symbol as
-deprecated using the following:
+Backward compatibility is important, so instead of a rename you need to deprecate
+the old name and introduce a new name:
 
 .. code-block:: nim
 
@@ -169,9 +172,6 @@ deprecated using the following:
 
   # for enum types ``deprecated`` is not yet supported.
 
-Note that currently the ``deprecated`` statement does not work well with
-overloading so for routines the latter variant is better.
-
 
 See also `Deprecated <https://nim-lang.org/docs/manual.html#pragmas-deprecated-pragma>`_
 pragma in the manual.
@@ -180,8 +180,8 @@ pragma in the manual.
 Documentation
 =============
 
-When contributing new procedures, be sure to add documentation, especially if
-the procedure is public. Documentation begins on the line
+When contributing new procs, be sure to add documentation, especially if
+the proc is public. Documentation begins on the line
 following the ``proc`` definition, and is prefixed by ``##`` on each line.
 
 Runnable code examples are also encouraged, to show typical behavior with a few
@@ -194,7 +194,7 @@ as well as ``testament`` and guarantee they stay in sync.
     ## Adds "Bar" to ``a``.
     runnableExamples:
       doAssert "baz".addBar == "bazBar"
-     
+
      result = a & "Bar"
 
 See `parentDir <https://nim-lang.github.io/Nim/ospaths.html#parentDir%2Cstring>`_