Add CONTRIBUTING.rst

Author: dolfinus

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+<!-- Thank you for your contribution! -->
+<!-- Unless your change is trivial, please create an issue to discuss the change before creating a PR -->
+<!-- See https://github.com/dolfinus/setuptools-git-versioning/blob/master/CONTRIBUTING.rst for help on Contributing -->
+<!-- PLEASE DO **NOT** put issue ids in the PR title! Instead, add a descriptive title and put ids in the body -->
+
+## Change Summary
+
+<!-- Please give a short summary of the changes. -->
+
+## Related issue number
+
+<!-- Are there any issues opened that will be resolved by merging this change? -->
+<!-- WARNING: please use "fix #123" style references so the issue is closed when this PR is merged. -->
+
+## Checklist
+
+* [ ] Commit message and PR title is comprehensive
+* [ ] Keep the change as small as possible
+* [ ] Unit and integration tests for the changes exist
+* [ ] Tests pass on CI and coverage does not decrease
+* [ ] Documentation reflects the changes where applicable
+* [ ] `docs/changelog/next_release/<pull request or issue id>.<change type>.rst` file added describing change
+  (see [CONTRIBUTING.rst](https://github.com/dolfinus/setuptools-git-versioning/blob/master/CONTRIBUTING.rst) for details.)
+* [ ] My PR is ready to review.

CONTRIBUTING.rst

@@ -0,0 +1,309 @@
+Contributing Guide
+==================
+
+Welcome! There are many ways to contribute, including submitting bug
+reports, improving documentation, submitting feature requests, reviewing
+new submissions, or contributing code that can be incorporated into the
+project.
+
+Review process
+--------------
+
+For any **significant** changes please create a new GitHub issue and
+enhancements that you wish to make. Describe the feature you would like
+to see, why you need it, and how it will work. Discuss your ideas
+transparently and get community feedback before proceeding.
+
+Small changes can directly be crafted and submitted to the GitHub
+Repository as a Pull Request. This requires creating a **repo fork** using
+`instruction <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_.
+
+Important notes
+---------------
+
+Please take into account that some users still use EOF Python versions, like 3.7. So it is required to keep compatibility if possible.
+
+Initial setup for local development
+-----------------------------------
+
+Install Git
+~~~~~~~~~~~
+
+Please follow `instruction <https://docs.github.com/en/get-started/quickstart/set-up-git>`_.
+
+Clone the repo
+~~~~~~~~~~~~~~
+
+Open terminal and run these commands to clone a **forked** repo:
+
+.. code:: bash
+
+    git clone git@github.com:myuser/setuptools-git-versioning.git -b develop
+
+    cd setuptools_git_versioning
+
+Enable pre-commit hooks
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Create virtualenv and install dependencies:
+
+.. code:: bash
+
+    make venv-install
+
+Install pre-commit hooks:
+
+.. code:: bash
+
+    prek install --install-hooks
+
+Test pre-commit hooks run:
+
+.. code:: bash
+
+    prek run
+
+How to
+------
+
+Run tests locally
+~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    You can skip this if only documentation is changed.
+
+Setup environment
+^^^^^^^^^^^^^^^^^
+
+Create virtualenv and install dependencies:
+
+.. code:: bash
+
+    make venv-install
+
+Run tests:
+
+.. code:: bash
+
+    make test
+
+Run specific tests:
+
+.. code:: bash
+
+    make test PYTEST_ARGS="-k some_test"
+
+You can pass additional arguments, they will be passed to pytest:
+
+.. code:: bash
+
+    make test PYTEST_ARGS="-k some_test -lsx -vvvv --log-cli-level=INFO"
+
+Build documentation
+~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    You can skip this if only source code behavior remains the same.
+
+Create virtualenv and install dependencies:
+
+.. code:: bash
+
+    make venv-install
+
+Build documentation using Sphinx:
+
+.. code:: bash
+
+    cd docs
+    make html
+
+Then open in browser ``docs/_build/index.html``.
+
+Create pull request
+~~~~~~~~~~~~~~~~~~~
+
+Commit your changes:
+
+.. code:: bash
+
+    git commit -m "Commit message"
+    git push
+
+Then open Github interface and `create pull request <https://docs.github.com/en/get-started/quickstart/contributing-to-projects#making-a-pull-request>`_.
+Please follow guide from PR body template.
+
+After pull request is created, it get a corresponding number, e.g. 123 (``pr_number``).
+
+Write release notes
+~~~~~~~~~~~~~~~~~~~
+
+``setuptools-git-versioning`` uses `towncrier <https://pypi.org/project/towncrier/>`_
+for changelog management.
+
+To submit a change note about your PR, add a text file into the
+`docs/changelog/next_release <./next_release>`_ folder. It should contain an
+explanation of what applying this PR will change in the way
+end-users interact with the project. One sentence is usually
+enough but feel free to add as many details as you feel necessary
+for the users to understand what it means.
+
+**Use the past tense** for the text in your fragment because,
+combined with others, it will be a part of the "news digest"
+telling the readers **what changed** in a specific version of
+the library *since the previous version*.
+
+You should also use
+reStructuredText syntax for highlighting code (inline or block),
+linking parts of the docs or external sites.
+If you wish to sign your change, feel free to add ``-- by
+:user:`github-username``` at the end (replace ``github-username``
+with your own!).
+
+Finally, name your file following the convention that Towncrier
+understands: it should start with the number of an issue or a
+PR followed by a dot, then add a patch type, like ``feature``,
+``doc``, ``misc`` etc., and add ``.rst`` as a suffix. If you
+need to add more than one fragment, you may add an optional
+sequence number (delimited with another period) between the type
+and the suffix.
+
+In general the name will follow ``<pr_number>.<category>.rst`` pattern,
+where the categories are:
+
+- ``feature``: Any new feature
+- ``bugfix``: A bug fix
+- ``improvement``: An improvement
+- ``doc``: A change to the documentation
+- ``dependency``: Dependency-related changes
+- ``misc``: Changes internal to the repo like CI, test and build changes
+
+A pull request may have more than one of these components, for example
+a code change may introduce a new feature that deprecates an old
+feature, in which case two fragments should be added. It is not
+necessary to make a separate documentation fragment for documentation
+changes accompanying the relevant code changes.
+
+Examples for adding changelog entries to your Pull Requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: rst
+    :caption: docs/changelog/next_release/1234.doc.1.rst
+
+    Added a ``:github:user:`` role to Sphinx config -- by :github:user:`someuser`
+
+.. code-block:: rst
+    :caption: docs/changelog/next_release/2345.bugfix.rst
+
+    Fixed behavior of ``WebDAV`` connector -- by :github:user:`someuser`
+
+.. code-block:: rst
+    :caption: docs/changelog/next_release/3456.feature.rst
+
+    Added support of ``timeout`` in ``S3`` connector
+    -- by :github:user:`someuser`, :github:user:`anotheruser` and :github:user:`otheruser`
+
+.. tip::
+
+    See `pyproject.toml <pyproject.toml>`_ for all available categories
+    (``tool.towncrier.type``).
+
+.. _Towncrier philosophy:
+    https://towncrier.readthedocs.io/en/stable/#philosophy
+
+How to skip change notes check?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Just add ``ci:skip-changelog`` label to pull request.
+
+Release Process
+---------------
+
+.. note::
+
+    This is for repo maintainers only
+
+Before making a release from the ``develop`` branch, follow these steps:
+
+0. Checkout to ``develop`` branch and update it to the actual state
+
+.. code:: bash
+
+    git checkout develop
+    git pull -p
+
+1. Backup ``NEXT_RELEASE.rst``
+
+.. code:: bash
+
+    cp "docs/changelog/NEXT_RELEASE.rst" "docs/changelog/temp_NEXT_RELEASE.rst"
+
+2. Build the Release notes with Towncrier
+
+.. code:: bash
+
+    VERSION=$(cat setuptools_git_versioning/VERSION)
+    towncrier build "--version=${VERSION}" --yes
+
+3. Change file with changelog to release version number
+
+.. code:: bash
+
+    mv docs/changelog/NEXT_RELEASE.rst "docs/changelog/${VERSION}.rst"
+
+4. Remove content above the version number heading in the ``${VERSION}.rst`` file
+
+.. code:: bash
+
+    awk '!/^.*towncrier release notes start/' "docs/changelog/${VERSION}.rst" > temp && mv temp "docs/changelog/${VERSION}.rst"
+
+5. Update Changelog Index
+
+.. code:: bash
+
+    awk -v version=${VERSION} '/DRAFT/{print;print "    " version;next}1' docs/changelog/index.rst > temp && mv temp docs/changelog/index.rst
+
+6. Restore ``NEXT_RELEASE.rst`` file from backup
+
+.. code:: bash
+
+    mv "docs/changelog/temp_NEXT_RELEASE.rst" "docs/changelog/NEXT_RELEASE.rst"
+
+7. Commit and push changes to ``develop`` branch
+
+.. code:: bash
+
+    git add .
+    git commit -m "Prepare for release ${VERSION}"
+    git push
+
+8. Merge ``develop`` branch to ``master``, **WITHOUT** squashing
+
+.. code:: bash
+
+    git checkout master
+    git pull
+    git merge develop
+    git push
+
+9. Add git tag to the latest commit in ``master`` branch
+
+.. code:: bash
+
+    git tag "$VERSION"
+    git push origin "$VERSION"
+
+10. Update version in ``develop`` branch **after release**:
+
+.. code:: bash
+
+    git checkout develop
+
+    NEXT_VERSION=$(echo "$VERSION" | awk -F. '/[0-9]+\./{$NF++;print}' OFS=.)
+    echo "$NEXT_VERSION" > setuptools_git_versioning/VERSION
+
+    git add .
+    git commit -m "Bump version"
+    git push