Repository navigation
Commit d387d91
chore(contributing): refresh development docs
1 parent bf46c67 commit d387d91
1 file changed
Lines changed: 40 additions & 33 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -12,50 +12,47 @@ You can contribute to the project in multiple ways: | |||
| 12 | 12 | Development workflow | |
| 13 | 13 | -------------------- | |
| 14 | 14 | ||
| 15 | - Before contributing, please make sure you have `pre-commit <https://pre-commit.com>`_ | ||
| 16 | - installed and configured. This will help automate adhering to code style and commit | ||
| 17 | - message guidelines described below: | ||
| 15 | + Before contributing, install `tox <https://tox.wiki/>`_ and `pre-commit <https://pre-commit.com>`_: | ||
| 18 | 16 | ||
| 19 | 17 | .. code-block:: bash | |
| 20 | 18 | ||
| 19 | + pip3 install --user tox pre-commit | ||
| 21 | 20 | cd python-gitlab/ | |
| 22 | - pip3 install --user pre-commit | ||
| 23 | 21 | pre-commit install -t pre-commit -t commit-msg --install-hooks | |
| 24 | 22 | ||
| 25 | - Please provide your patches as GitHub pull requests. Thanks! | ||
| 23 | + This will help automate adhering to code style and commit message guidelines described below. | ||
| 26 | 24 | ||
| 27 | - Rerunning failed CI workflows | ||
| 28 | - ----------------------------- | ||
| 25 | + If you don't like using ``pre-commit``, feel free to skip installing it, but please **ensure all your | ||
| 26 | + commit messages and code pass all default tox checks** outlined below before pushing your code. | ||
| 29 | 27 | ||
| 30 | - * Ask the maintainers to add the ``ok-to-test`` label on the PR | ||
| 31 | - * Post a comment in the PR | ||
| 32 | - ``/rerun-all`` - rerun all failed workflows | ||
| 33 | - | ||
| 34 | - ``/rerun-workflow <workflow name>`` - rerun a specific failed workflow | ||
| 35 | - | ||
| 36 | - The functionality is provided by ``rerun-action <https://github.com/marketplace/actions/rerun-actions>`` | ||
| 28 | + When you're ready or if you'd like to get feedback, please provide your patches as Pull Requests on GitHub. | ||
| 37 | 29 | ||
| 38 | 30 | Commit message guidelines | |
| 39 | 31 | ------------------------- | |
| 40 | 32 | ||
| 41 | - We enforce commit messages to be formatted using the `conventional-changelog <https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit>`_. | ||
| 42 | - This leads to more readable messages that are easy to follow when looking through the project history. | ||
| 33 | + We enforce commit messages to be formatted using the `Conventional Commits <https://www.conventionalcommits.org/>`_. | ||
| 34 | + This creates a clearer project history, and automates our `Releases`_ and changelog generation. Examples: | ||
| 35 | + | ||
| 36 | + * Bad: ``Added support for release links`` | ||
| 37 | + * Good: ``feat(api): add support for release links`` | ||
| 43 | 38 | ||
| 44 | - Code-Style | ||
| 45 | - ---------- | ||
| 39 | + * Bad: ``Update documentation for projects`` | ||
| 40 | + * Good: ``docs(projects): update example for saving project attributes`` | ||
| 46 | 41 | ||
| 47 | - We use black as code formatter, so you'll need to format your changes using the | ||
| 48 | - `black code formatter | ||
| 49 | - <https://github.com/python/black>`_. Pre-commit hooks will validate/format your code | ||
| 50 | - when committing. You can then stage any changes ``black`` added if the commit failed. | ||
| 42 | + Coding Style | ||
| 43 | + ------------ | ||
| 44 | + | ||
| 45 | + We use `black<https://github.com/python/black>`_ and `isort <https://pycqa.github.io/isort/>`_ | ||
| 46 | + to format our code, so you'll need to make sure you use it when committing. | ||
| 47 | + | ||
| 48 | + Pre-commit hooks will validate and format your code, so you can then stage any changes done if the commit failed. | ||
| 51 | 49 | ||
| 52 | 50 | To format your code according to our guidelines before committing, run: | |
| 53 | 51 | ||
| 54 | 52 | .. code-block:: bash | |
| 55 | 53 | ||
| 56 | 54 | cd python-gitlab/ | |
| 57 | - pip3 install --user black | ||
| 58 | - black . | ||
| 55 | + tox -e black,isort | ||
| 59 | 56 | ||
| 60 | 57 | Running unit tests | |
| 61 | 58 | ------------------ | |
@@ -72,18 +69,17 @@ You need to install ``tox`` (``pip3 install tox``) to run tests and lint checks | |||
| 72 | 69 | ||
| 73 | 70 | .. code-block:: bash | |
| 74 | 71 | ||
| 75 | - # run unit tests using your installed python3, and all lint checks: | ||
| 76 | - tox -s | ||
| 77 | - | ||
| 78 | - # run unit tests for all supported python3 versions, and all lint checks: | ||
| 72 | + # run unit tests using all python3 versions available on your system, and all lint checks: | ||
| 79 | 73 | tox | |
| 80 | 74 | ||
| 81 | - # run tests in one environment only: | ||
| 82 | - tox -epy38 | ||
| 75 | + # run unit tests in one python environment only (useful for quick testing during development): | ||
| 76 | + tox -e py311 | ||
| 83 | 77 | ||
| 84 | - # build the documentation, the result will be generated in | ||
| 85 | - # build/sphinx/html/ | ||
| 86 | - tox -edocs | ||
| 78 | + # build the documentation - the result will be generated in build/sphinx/html/: | ||
| 79 | + tox -e docs | ||
| 80 | + | ||
| 81 | + # List all available tox environments | ||
| 82 | + tox list | ||
| 87 | 83 | ||
| 88 | 84 | Running integration tests | |
| 89 | 85 | ------------------------- | |
@@ -145,6 +141,17 @@ To cleanup the environment delete the container: | |||
| 145 | 141 | docker rm -f gitlab-test | |
| 146 | 142 | docker rm -f gitlab-runner-test | |
| 147 | 143 | ||
| 144 | + Rerunning failed CI workflows | ||
| 145 | + ----------------------------- | ||
| 146 | + | ||
| 147 | + * Ask the maintainers to add the ``ok-to-test`` label on the PR | ||
| 148 | + * Post a comment in the PR | ||
| 149 | + ``/rerun-all`` - rerun all failed workflows | ||
| 150 | + | ||
| 151 | + ``/rerun-workflow <workflow name>`` - rerun a specific failed workflow | ||
| 152 | + | ||
| 153 | + The functionality is provided by ``rerun-action <https://github.com/marketplace/actions/rerun-actions>`` | ||
| 154 | + | ||
| 148 | 155 | Releases | |
| 149 | 156 | -------- | |
| 150 | 157 | ||
0 commit comments