Add Origin-upstream page

Makefile

@@ -89,13 +89,12 @@ prepare-release:
 	@python3 -u tools/prepare-release.py -v $(VERSION) -rd $(ROOT_DIR) -r
 
 docs-pictures:
+	@python3 tools/plot-repositories.py
 	@python3 tools/plot-package-scheme.py
 	@python3 tools/plot-atom-magnetic-properties.py
 
 .ONESHELL:
-venv:
-	@rm -r .venv
-	@python3 -m venv .venv
+requirements:
 	@pip install -r requirements.txt --no-cache
 	@pip install -r requirements-dev.txt --no-cache
 	@pip install -r docs/requirements.txt --no-cache

docs/source/conf.py

@@ -225,7 +225,7 @@
         "Array interface",
         "https://numpy.org/doc/stable/reference/arrays.interface.html#object.__array_interface__",
     ),
-    "repo": ("wulfric repository", "https://github.com/adrybakov/wulfric"),
+    "repo": ("Wulfric repository", "https://github.com/adrybakov/wulfric"),
     "numpydoc": ("numpydoc", "https://numpydoc.readthedocs.io/en/latest/format.html"),
     "plotly": ("Plotly", "https://plotly.com/python/"),
     "plotly-update-layout": (

docs/source/contribute/contributors.rst

@@ -1,4 +1,3 @@
-
 .. _contribute_contributors:
 
 Contributors

docs/source/contribute/index.rst

@@ -26,98 +26,125 @@ Development workflow
 For the detailed explanation of the development workflow, please visit
 the corresponding links below.
 
-1. Fork and clone.
+Fork and clone
+--------------
 
-   * Go to the |repo|_ and click on the "Fork" button.
-     Now you have your own copy of the Wulfric repository in your GitHub account.
-   * Clone your copy of the repository to your local machine:
+* Go to the |repo|_ and click on the "Fork" button.
+  Now you have your own copy of the Wulfric repository in your GitHub account.
+* Clone your copy of the repository to your local machine:
 
-     - If you are using ssh-key::
+  - If you are using ssh-key::
 
-         git clone [email protected]:your-username/wulfric.git
+      git clone [email protected]:your-username/wulfric.git
 
-     - If you are not using ssh-key::
+  - If you are not using ssh-key::
 
-         git clone https://github.com/your-username/wulfric.git
+      git clone https://github.com/your-username/wulfric.git
 
-   * Change the directory::
+* Change the directory::
 
-      cd wulfric
+    cd wulfric
 
-   * Add the upstream repository::
+* Add the :ref:`upstream <contribute_origin-upstream>` repository::
 
-      git remote add upstream https://github.com/adrybakov/wulfric.git
+    git remote add upstream https://github.com/adrybakov/wulfric.git
 
-2. Set up the environment.
+* Pull the latest changes from the Wulfric repository in necessary::
 
-   We recommend to use virtual environment. Once the virtual environment is created,
-   you can install requirements:
+    git pull upstream main
 
-   * Package dependencies::
+Set up the environment
+----------------------
 
-      pip install -r requirements.txt
+We recommend to use virtual environment. Once the virtual environment is created,
+you can install requirements:
 
-   * For the package development::
+* Package dependencies::
 
-      pip install -r requirements-dev.txt
+    pip install -r requirements.txt
 
-   * For the documentation::
+* For the package development::
 
-      pip install -r docs/requirements.txt
+    pip install -r requirements-dev.txt
 
-   * For the tests::
+* For the documentation::
 
-      pip install -r utest/requirements.txt
+    pip install -r docs/requirements.txt
 
-   .. note::
-      For the linux and OSX systems there is a scenario defined::
+* For the tests::
 
-         make venv
+    pip install -r utest/requirements.txt
 
-3. Develop the contribution.
+.. note::
+  For the linux and OSX systems there is a scenario defined.
+  It installs all requirements. Note: it does NOT create an environment for you::
 
-   * Create a dedicated branch for your feature, that you are going to develop::
+    make requirements
 
-      git checkout -b feature-name
+Enable pre-commit
+-----------------
 
-   * Develop your contribution. Commit your progress locally
-     (`git-add <https://git-scm.com/docs/git-add>`_
-     and `git-commit <https://git-scm.com/docs/git-commit>`_).
-     Use meaningful commit messages. Write :ref:`tests <contribute_tests>`.
-     Write :ref:`documentation <contribute_docs>`.
+We use `pre-commit <https://pre-commit.com/>`_ to enforce some rules on the code style
+before each commit.
+To enable it, run the following command::
 
-4. Submit your contribution.
+  pre-commit install
 
-   * Push the changes to your forked repository::
+Now, every time you commit the code, pre-commit will check it for you.
 
-      git push origin feature-name
+.. hint::
+  If you want to run pre-commit manually, you can use the following command::
 
-   * Go to your forked repository on GitHub and click on the
-     green "Compare & pull request" button.
-     Describe your contribution and submit the pull request.
-     Please mention the issue number if it is related to any.
+    pre-commit run --all-files
 
-5. Review and merge.
+Develop your contribution
+-------------------------
 
-   * Once the pull request is submitted, the code will be reviewed.
-     If there are any comments, please fix them.
-   * Once the pull request is approved, it will be merged to the
-     `stable <https://github.com/adrybakov/wulfric>`_ or
-     `dev <https://github.com/adrybakov/wulfric/tree/dev>`_ branch.
+* Create a dedicated branch for your feature, that you are going to develop::
+
+    git checkout -b feature-name
+
+* Develop your contribution. Commit your progress locally
+  (`git-add <https://git-scm.com/docs/git-add>`_
+  and `git-commit <https://git-scm.com/docs/git-commit>`_).
+  Use meaningful commit messages. Write :ref:`tests <contribute_tests>`.
+  Write :ref:`documentation <contribute_docs>`.
+
+Submit your contribution
+------------------------
+
+* Push the changes to your forked repository::
+
+    git push origin feature-name
+
+* Go to your forked repository on GitHub and click on the
+  green "Compare & pull request" button.
+  Describe your contribution and submit the pull request.
+  Please mention the issue number if it is related to any.
+
+Review and merge
+----------------
+
+* Once the pull request is submitted, the code will be reviewed.
+  If there are any comments, please fix them.
+* Once the pull request is approved, it will be merged to the
+  `stable <https://github.com/adrybakov/wulfric>`_ or
+  `dev <https://github.com/adrybakov/wulfric/tree/dev>`_ branch.
 
 
 Development process in details
 ==============================
 
 .. toctree::
-   :hidden:
+  :hidden:
 
-   contributors
+  contributors
 
 .. toctree::
-   :maxdepth: 2
+  :maxdepth: 2
 
-   features
-   bugs
-   documentation
-   tests
+  features
+  bugs
+  documentation
+  tests
+  origin-upstream

docs/source/contribute/origin-upstream.rst

@@ -0,0 +1,45 @@
+.. _contribute_origin-upstream:
+
+*******************
+Origin and Upstream
+*******************
+
+We use the terminology **Upstream** and **Origin** to refer to the two remote repositories
+that are used in the development process. The picture below summaries the relationship
+between the two repositories and the local repository with the most common communications
+between them:
+
+.. figure:: img/origin-upstream-local.png
+    :target: ../_images/origin-upstream-local.png
+    :align: center
+
+Origin repository
+=================
+
+We refer to the Wulfric repository under **your** personal account as the **Origin**
+repository.
+
+During the development it is the repository that you will be pushing your changes to.
+Once the feature you're working on is ready, you will create a pull request from the
+**Origin** repository to the **Upstream** repository.
+
+Upstream repository
+===================
+
+We refer to the main |repo|_, from which the release is made, as the **Upstream** repository.
+
+At the moment it is a repository under the account of the main developer of Wulfric,
+but in principle it may be moved to a different personal or organization's account
+in the future.
+
+You can pull changes from the **Upstream** repository to your local repository to keep
+it up to date with the latest changes in the **Upstream** repository. Alternatively,
+you can  *sync fork* from the github interface to keep your **Origin** repository up to
+date with the **Upstream** repository.
+
+Local repository
+================
+
+The local repository is the repository on your computer where you will be making
+changes to the code and committing them. Typically, you will be pushing your changes to the
+**Origin** repository and pulling changes of other people from the **Upstream** repository.