FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

docs(readme): move contributing docs to CONTRIBUTING.rst · python-gitlab/python-gitlab@edf49a3 · GitHub

  1. python-gitlab
  2. python-gitlab

Repository navigation

Commit edf49a3

Browse files
iamed2
authored and
JohnVillalovos
committed
docs(readme): move contributing docs to CONTRIBUTING.rst
Move the Contributing section of README.rst to CONTRIBUTING.rst, so it is recognized by GitHub and shown when new contributors make pull requests.
1 parent 98cd03b commit edf49a3

2 files changed

Lines changed: 162 additions & 158 deletions

File tree

‎CONTRIBUTING.rst‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
Contributing
2+
============
3+
4+
You can contribute to the project in multiple ways:
5+
6+
* Write documentation
7+
* Implement features
8+
* Fix bugs
9+
* Add unit and functional tests
10+
* Everything else you can think of
11+
12+
Development workflow
13+
--------------------
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:
18+
19+
.. code-block:: bash
20+
21+
cd python-gitlab/
22+
pip3 install --user pre-commit
23+
pre-commit install -t pre-commit -t commit-msg --install-hooks
24+
25+
Please provide your patches as GitHub pull requests. Thanks!
26+
27+
Commit message guidelines
28+
-------------------------
29+
30+
We enforce commit messages to be formatted using the `conventional-changelog <https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines>`_.
31+
This leads to more readable messages that are easy to follow when looking through the project history.
32+
33+
Code-Style
34+
----------
35+
36+
We use black as code formatter, so you'll need to format your changes using the
37+
`black code formatter
38+
<https://github.com/python/black>`_. Pre-commit hooks will validate/format your code
39+
when committing. You can then stage any changes ``black`` added if the commit failed.
40+
41+
To format your code according to our guidelines before committing, run:
42+
43+
.. code-block:: bash
44+
45+
cd python-gitlab/
46+
pip3 install --user black
47+
black .
48+
49+
Running unit tests
50+
------------------
51+
52+
Before submitting a pull request make sure that the tests and lint checks still succeed with
53+
your change. Unit tests and functional tests run in GitHub Actions and
54+
passing checks are mandatory to get merge requests accepted.
55+
56+
Please write new unit tests with pytest and using `responses
57+
<https://github.com/getsentry/responses/>`_.
58+
An example can be found in ``tests/unit/objects/test_runner.py``
59+
60+
You need to install ``tox`` (``pip3 install tox``) to run tests and lint checks locally:
61+
62+
.. code-block:: bash
63+
64+
# run unit tests using your installed python3, and all lint checks:
65+
tox -s
66+
67+
# run unit tests for all supported python3 versions, and all lint checks:
68+
tox
69+
70+
# run tests in one environment only:
71+
tox -epy38
72+
73+
# build the documentation, the result will be generated in
74+
# build/sphinx/html/
75+
tox -edocs
76+
77+
Running integration tests
78+
-------------------------
79+
80+
Integration tests run against a running gitlab instance, using a docker
81+
container. You need to have docker installed on the test machine, and your user
82+
must have the correct permissions to talk to the docker daemon.
83+
84+
To run these tests:
85+
86+
.. code-block:: bash
87+
88+
# run the CLI tests:
89+
tox -e cli_func_v4
90+
91+
# run the python API tests:
92+
tox -e py_func_v4
93+
94+
When developing tests it can be a little frustrating to wait for GitLab to spin
95+
up every run. To prevent the containers from being cleaned up afterwards, pass
96+
`--keep-containers` to pytest, i.e.:
97+
98+
.. code-block:: bash
99+
100+
tox -e py_func_v4 -- --keep-containers
101+
102+
If you then wish to test against a clean slate, you may perform a manual clean
103+
up of the containers by running:
104+
105+
.. code-block:: bash
106+
107+
docker-compose -f tests/functional/fixtures/docker-compose.yml -p pytest-python-gitlab down -v
108+
109+
By default, the tests run against the latest version of the ``gitlab/gitlab-ce``
110+
image. You can override both the image and tag by providing either the
111+
``GITLAB_IMAGE`` or ``GITLAB_TAG`` environment variables.
112+
113+
This way you can run tests against different versions, such as ``nightly`` for
114+
features in an upcoming release, or an older release (e.g. ``12.8.0-ce.0``).
115+
The tag must match an exact tag on Docker Hub:
116+
117+
.. code-block:: bash
118+
119+
# run tests against `nightly` or specific tag
120+
GITLAB_TAG=nightly tox -e py_func_v4
121+
GITLAB_TAG=12.8.0-ce.0 tox -e py_func_v4
122+
123+
# run tests against the latest gitlab EE image
124+
GITLAB_IMAGE=gitlab/gitlab-ee tox -e py_func_v4
125+
126+
A freshly configured gitlab container will be available at
127+
http://localhost:8080 (login ``root`` / password ``5iveL!fe``). A configuration
128+
for python-gitlab will be written in ``/tmp/python-gitlab.cfg``.
129+
130+
To cleanup the environment delete the container:
131+
132+
.. code-block:: bash
133+
134+
docker rm -f gitlab-test
135+
docker rm -f gitlab-runner-test
136+
137+
Releases
138+
--------
139+
140+
A release is automatically published once a month on the 28th if any commits merged
141+
to the main branch contain commit message types that signal a semantic version bump
142+
(``fix``, ``feat``, ``BREAKING CHANGE:``).
143+
144+
Additionally, the release workflow can be run manually by maintainers to publish urgent
145+
fixes, either on GitHub or using the ``gh`` CLI with ``gh workflow run release.yml``.
146+
147+
**Note:** As a maintainer, this means you should carefully review commit messages
148+
used by contributors in their pull requests. If scopes such as ``fix`` and ``feat``
149+
are applied to trivial commits not relevant to end users, it's best to squash their
150+
pull requests and summarize the addition in a single conventional commit.
151+
This avoids triggering incorrect version bumps and releases without functional changes.
152+
153+
The release workflow uses `python-semantic-release
154+
<https://python-semantic-release.readthedocs.io>`_ and does the following:
155+
156+
* Bumps the version in ``__version__.py`` and adds an entry in ``CHANGELOG.md``,
157+
* Commits and tags the changes, then pushes to the main branch as the ``github-actions`` user,
158+
* Creates a release from the tag and adds the changelog entry to the release notes,
159+
* Uploads the package as assets to the GitHub release,
160+
* Uploads the package to PyPI using ``PYPI_TOKEN`` (configured as a secret).

‎README.rst‎

Lines changed: 2 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
.. image:: https://img.shields.io/gitter/room/python-gitlab/Lobby.svg
1717
:target: https://gitter.im/python-gitlab/Lobby
18-
18+
1919
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
2020
:target: https://github.com/python/black
2121

@@ -96,160 +96,4 @@ You can build the documentation using ``sphinx``::
9696
Contributing
9797
============
9898

99-
You can contribute to the project in multiple ways:
100-
101-
* Write documentation
102-
* Implement features
103-
* Fix bugs
104-
* Add unit and functional tests
105-
* Everything else you can think of
106-
107-
Development workflow
108-
--------------------
109-
110-
Before contributing, please make sure you have `pre-commit <https://pre-commit.com>`_
111-
installed and configured. This will help automate adhering to code style and commit
112-
message guidelines described below:
113-
114-
.. code-block:: bash
115-
116-
cd python-gitlab/
117-
pip3 install --user pre-commit
118-
pre-commit install -t pre-commit -t commit-msg --install-hooks
119-
120-
Please provide your patches as GitHub pull requests. Thanks!
121-
122-
Commit message guidelines
123-
-------------------------
124-
125-
We enforce commit messages to be formatted using the `conventional-changelog <https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines>`_.
126-
This leads to more readable messages that are easy to follow when looking through the project history.
127-
128-
Code-Style
129-
----------
130-
131-
We use black as code formatter, so you'll need to format your changes using the
132-
`black code formatter
133-
<https://github.com/python/black>`_. Pre-commit hooks will validate/format your code
134-
when committing. You can then stage any changes ``black`` added if the commit failed.
135-
136-
To format your code according to our guidelines before committing, run:
137-
138-
.. code-block:: bash
139-
140-
cd python-gitlab/
141-
pip3 install --user black
142-
black .
143-
144-
Running unit tests
145-
------------------
146-
147-
Before submitting a pull request make sure that the tests and lint checks still succeed with
148-
your change. Unit tests and functional tests run in GitHub Actions and
149-
passing checks are mandatory to get merge requests accepted.
150-
151-
Please write new unit tests with pytest and using `responses
152-
<https://github.com/getsentry/responses/>`_.
153-
An example can be found in ``tests/unit/objects/test_runner.py``
154-
155-
You need to install ``tox`` (``pip3 install tox``) to run tests and lint checks locally:
156-
157-
.. code-block:: bash
158-
159-
# run unit tests using your installed python3, and all lint checks:
160-
tox -s
161-
162-
# run unit tests for all supported python3 versions, and all lint checks:
163-
tox
164-
165-
# run tests in one environment only:
166-
tox -epy38
167-
168-
# build the documentation, the result will be generated in
169-
# build/sphinx/html/
170-
tox -edocs
171-
172-
Running integration tests
173-
-------------------------
174-
175-
Integration tests run against a running gitlab instance, using a docker
176-
container. You need to have docker installed on the test machine, and your user
177-
must have the correct permissions to talk to the docker daemon.
178-
179-
To run these tests:
180-
181-
.. code-block:: bash
182-
183-
# run the CLI tests:
184-
tox -e cli_func_v4
185-
186-
# run the python API tests:
187-
tox -e py_func_v4
188-
189-
When developing tests it can be a little frustrating to wait for GitLab to spin
190-
up every run. To prevent the containers from being cleaned up afterwards, pass
191-
`--keep-containers` to pytest, i.e.:
192-
193-
.. code-block:: bash
194-
195-
tox -e py_func_v4 -- --keep-containers
196-
197-
If you then wish to test against a clean slate, you may perform a manual clean
198-
up of the containers by running:
199-
200-
.. code-block:: bash
201-
202-
docker-compose -f tests/functional/fixtures/docker-compose.yml -p pytest-python-gitlab down -v
203-
204-
By default, the tests run against the latest version of the ``gitlab/gitlab-ce``
205-
image. You can override both the image and tag by providing either the
206-
``GITLAB_IMAGE`` or ``GITLAB_TAG`` environment variables.
207-
208-
This way you can run tests against different versions, such as ``nightly`` for
209-
features in an upcoming release, or an older release (e.g. ``12.8.0-ce.0``).
210-
The tag must match an exact tag on Docker Hub:
211-
212-
.. code-block:: bash
213-
214-
# run tests against `nightly` or specific tag
215-
GITLAB_TAG=nightly tox -e py_func_v4
216-
GITLAB_TAG=12.8.0-ce.0 tox -e py_func_v4
217-
218-
# run tests against the latest gitlab EE image
219-
GITLAB_IMAGE=gitlab/gitlab-ee tox -e py_func_v4
220-
221-
A freshly configured gitlab container will be available at
222-
http://localhost:8080 (login ``root`` / password ``5iveL!fe``). A configuration
223-
for python-gitlab will be written in ``/tmp/python-gitlab.cfg``.
224-
225-
To cleanup the environment delete the container:
226-
227-
.. code-block:: bash
228-
229-
docker rm -f gitlab-test
230-
docker rm -f gitlab-runner-test
231-
232-
Releases
233-
--------
234-
235-
A release is automatically published once a month on the 28th if any commits merged
236-
to the main branch contain commit message types that signal a semantic version bump
237-
(``fix``, ``feat``, ``BREAKING CHANGE:``).
238-
239-
Additionally, the release workflow can be run manually by maintainers to publish urgent
240-
fixes, either on GitHub or using the ``gh`` CLI with ``gh workflow run release.yml``.
241-
242-
**Note:** As a maintainer, this means you should carefully review commit messages
243-
used by contributors in their pull requests. If scopes such as ``fix`` and ``feat``
244-
are applied to trivial commits not relevant to end users, it's best to squash their
245-
pull requests and summarize the addition in a single conventional commit.
246-
This avoids triggering incorrect version bumps and releases without functional changes.
247-
248-
The release workflow uses `python-semantic-release
249-
<https://python-semantic-release.readthedocs.io>`_ and does the following:
250-
251-
* Bumps the version in ``__version__.py`` and adds an entry in ``CHANGELOG.md``,
252-
* Commits and tags the changes, then pushes to the main branch as the ``github-actions`` user,
253-
* Creates a release from the tag and adds the changelog entry to the release notes,
254-
* Uploads the package as assets to the GitHub release,
255-
* Uploads the package to PyPI using ``PYPI_TOKEN`` (configured as a secret).
99+
For guidelines for contributing to ``python-gitlab``, refer to `CONTRIBUTING.rst <https://github.com/python-gitlab/python-gitlab/blob/master/CONTRIBUTING.rst>`_.

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL