Merge pull request #298 from iiasa/release-2.0

Release v2.0.0

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,13 +1,44 @@
+<!-- Delete each of these instruction comments as you complete it. -->
+
+<!-- Title: use a short, declarative statement similar to a commit message,
+     e.g. “Change [thing X] to [fix solve bug|enable feature Y]” -->
+
 **Required:** write a single sentence here describing the changes made by this PR.
 
-(Optional: write a longer description here to help a reviewer understand the PR in 3–5 minutes.)
+<!-- Optional: write a longer description here to help a reviewer understand the PR in 3–5 minutes. -->
+
+## How to review
+
+**Required:** describe specific things that reviewer(s) need to do to, in order
+to ensure that the PR does what it intends.
+
+<!-- For example:
 
-**PR checklist:**
+- Run a specific code snippet or command and check the output.
+- Build the documentation and look at a certain.
+- Simply view changes and note that the CI checks all pass.
+- Ensure that changes/additions are self-documenting, i.e. that another
+  developer like the reviewer will be able to understand what the code does
+  in the future.
+-->
+
+## PR checklist
+
+<!-- The following items are all **required* if the PR results in changes to
+the user behaviour, e.g. new features or fixes to existing behaviour. They are
+**optional** if the changes are solely to documentation, CI configuration, etc.
+
+In ambiguous cases, strike them out and add a short explanation, e.g.
+
+- [x] ~Tests added.~ No change in behaviour, simply refactoring.
+-->
 
 - [ ] Tests added.
 - [ ] Documentation added.
-- [ ] Release notes updated. Add a single line at the top of `RELEASE_NOTES.md` similar to…
-  ```
-  - [#999](https://github.com/iiasa/message_ix/pull/999) Description from above.
-  ```
-  …then, delete this sentence to confirm you've understood the instructions.
+- [ ] Release notes updated.
+  <!-- To update `RELEASE_NOTES.rst`, add a single line under the section
+  “Next release” similar to:
+
+  - `#999 <https://github.com/iiasa/message_ix/pull/999>`_: Title or single-
+    sentence description from above.
+  -->

CONTRIBUTING.rst

@@ -13,16 +13,17 @@ Filing issues for bugs and enhancements
 
 We use Github **issues** for several purposes:
 
-- Ask and answer questions about intended behaviour or issues running the framework or related models.
-- Report bugs, i.e. unintended or undocumented behaviour.
-- Request changes to behaviour.
-- Request specific enhancements and new features, both urgent and long-term/low-priority.
+- Ask and answer *questions* about intended behaviour or issues running the framework or related models.
+- Report *bugs*, i.e. unintended or undocumented behaviour.
+- Request *changes* to exiting behaviour.
+- Request specific *enhancements* and *new features*, both urgent and long-term/low-priority.
 - Discuss and design of other improvements.
 
-Please search through open *and* closed issues for *both* the `message_ix <https://github.com/iiasa/message_ix/issues?q=is:issue>`_ and `ixmp <https://github.com/iiasa/ixmp/issues?q=is:issue>`_ repositories.
+Please search through open *and* closed issues for *both* the `message_ix`__ and `ixmp <https://github.com/iiasa/ixmp/issues?q=is:issue>`_ repositories.
 Review any related issues.
 Then, if your issue is not found, `open a new one <https://github.com/iiasa/message_ix/issues/new>`_.
 
+__ https://github.com/iiasa/message_ix/issues?q=is:issue
 
 Contributing code via Github PRs
 --------------------------------
@@ -34,18 +35,20 @@ Register a Github account, if you do not already have one.
 1. Choose a repository
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Decide: to which part of the |MESSAGEix| software stack should your code be added?
+Decide which part of the |MESSAGEix| software stack is the appropriate location for your code:
 
-``ixmp``
+:mod:`ixmp`
    Contributions not specific to |MESSAGEix| model framework, e.g. that could be used for other, non-MESSAGE models.
-``message_ix``
+
+   :mod:`ixmp_source`
+      Java / JDBC backend for ``ixmp``.
+
+:mod:`message_ix`
    Contributions not specific to *any particular MESSAGEix* model instance.
    Additions to ``message_ix`` should be usable in any MESSAGE-scheme model.
-``message_data`` or ``message_doc``
+:mod:`message_data` or :mod:`message_doc`
    Contributions to the MESSAGE-GLOBIOM family of models, including the global
    model; and its documentation, respectively.
-``ixmp_source``
-   Java / JDBC backend for ``ixmp``.
 
 2. Fork, branch, and open a pull request
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -57,9 +60,11 @@ Create a branch with an appropriate name:
 - ``issue/1234`` if you are addressing a specific issue.
 - ``feature/do-something`` if you are adding a new feature.
 
-Open a PR (e.g. on `message_ix <https://github.com/iiasa/message_ix/pulls>`_) to merge your code into the ``master`` branch.
+Open a PR (e.g. on `message_ix`__) to merge your code into the ``master`` branch.
 The ``message_ix`` and ``ixmp`` repositories each have a template for the text of the PR, including the minimum requirements:
 
+__ https://github.com/iiasa/message_ix/pulls
+
 - A title and one-sentence summary of the change.
   This is like the abstract of a publication: it should help a developer/reviewer/user quickly learn what the PR is about.
 - Confirm that unit or integration tests have been added or revised to cover the changed code, and that the tests pass (see below).
@@ -69,9 +74,11 @@ The ``message_ix`` and ``ixmp`` repositories each have a template for the text o
 Optionally:
 
 - Include a longer description of the design, or any changes whose purpose is not clear by inspecting code.
-- Put “WIP:” at the start of the PR title to indicate “work in progress” while you continue to add commits.
+- Put “WIP:” or the construction sign Unicode character (🚧) at the start of the PR title to indicate “work in progress” while you continue to add commits; or use GitHub's `'draft' pull requests`__.
   This is good development practice: it ensures the automatic checks pass as you add to the code on your branch.
 
+__ https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests
+
 3. Ensure checks pass
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -125,7 +132,7 @@ Versions and releases
 ---------------------
 
 - We use `semantic versioning <https://semver.org>`_.
-- We keep at least two active milestones on each of the ``message_ix`` and ``ixmp`` repositories:
+- We keep at least two active milestones on each of the message_ix and ixmp repositories:
 
   - The next minor version. E.g. if the latest release was 3.5, the next minor release/milestone is 3.6.
   - The next major version. E.g. 4.0.
@@ -142,9 +149,9 @@ Contributing tutorials
 ----------------------
 
 Developers *and users* of the |MESSAGEix| framework are welcome to contribute **tutorials**, according to the following guidelines.
-Per the license and CLA, tutorials will become part of the ``message_ix`` test suite and will be publicly available.
+Per the license and CLA, tutorials will become part of the message_ix test suite and will be publicly available.
 
-Developers **must** ensure new features (including ``message_ix.tools`` submodules) are fully documented.
+Developers **must** ensure new features (including :mod:`message_ix.tools` submodules) are fully documented.
 This can be done via the API documentation (this site) and, optionally, a tutorial.
 These have complementary purposes: