Skip to content

Commit e6c6841

Browse files
JohnVillalovosJohnVillalovos
committed
docs: add the start of a contributor's guide
Create an initial contributor's guide that will hopefully be expanded on in the future.
1 parent c6d7e9a commit e6c6841

File tree

4 files changed

+166
-0
lines changed

4 files changed

+166
-0
lines changed

‎docs/contributor/contributing.rst

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. _code-contribution-guide:
2+
3+
============================
4+
So You Want to Contribute...
5+
============================
6+
7+
This document provides some necessary points for developers to consider when
8+
writing and reviewing python-gitlab code. The checklist will help developers get
9+
things right.
10+
11+
Getting Started
12+
===============
13+
14+
If you're completely new to GitHub development and want to contribute to the
15+
python-gitlab project, please start by familiarizing yourself with the `GitHub
16+
Getting Started Guide <https://docs.github.com/en/get-started>`_. This will
17+
help you familiarize yourself with the workflow for the GitHub continuous
18+
integration and testing systems, and help you with your first commit.
19+
20+
Useful Links
21+
------------
22+
23+
Bug/Task tracker
24+
https://github.com/python-gitlab/python-gitlab/issues
25+
26+
Code Hosting
27+
https://github.com/python-gitlab/python-gitlab
28+
29+
Getting Your Patch Merged
30+
-------------------------
31+
32+
TODO: Document info that will be useful
33+
34+
Bug Reporting
35+
=============
36+
37+
Bugs can reported via our issue tracker at
38+
https://github.com/python-gitlab/python-gitlab/issues
39+
40+
When filing bugs, please include as much detail as possible, and don't be shy.
41+
42+
Essential pieces of information are generally:
43+
44+
* Steps to reproduce the issue.
45+
* Exceptions and surrounding lines from the logs.
46+
* Versions of python-gitlab and Gitlab.
47+
48+
Please also set your expectations of what *should* be happening.
49+
Statements of user expectations are how we understand what is occuring and
50+
how we learn new use cases!

‎docs/contributor/dev-quickstart.rst

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
.. _dev-quickstart:
2+
3+
=====================
4+
Developer Quick-Start
5+
=====================
6+
7+
This is a quick walkthrough to get you started developing code for
8+
python-gitlab. This assumes you are already familiar with submitting code
9+
reviews to a Github based project.
10+
11+
The CI (Continuous Integration) system currently runs the unit tests under
12+
Python 3.7, 3.8, 3.9, and 3.10. It is strongly encouraged to run the unit tests
13+
locally prior to submitting a patch.
14+
15+
Prepare Development System
16+
==========================
17+
18+
System Prerequisites
19+
--------------------
20+
21+
The following packages cover the prerequisites for a local development
22+
environment on most current distributions. Instructions for getting set up with
23+
non-default versions of Python and on older distributions are included below as
24+
well.
25+
26+
- Ubuntu/Debian::
27+
28+
sudo apt-get install python3-pip git
29+
30+
- RHEL/CentOS/Fedora::
31+
32+
sudo dnf install python3-pip git
33+
34+
Python Prerequisites
35+
--------------------
36+
37+
We suggest to use at least tox 3.24, if your distribution has an older version,
38+
you can install it using pip system-wise or better per user using the --user
39+
option that by default will install the binary under $HOME/.local/bin, so you
40+
need to be sure to have that path in $PATH; for example::
41+
42+
pip3 install tox --user
43+
44+
will install tox as ~/.local/bin/tox
45+
46+
You may need to explicitly upgrade virtualenv if you've installed the one
47+
from your OS distribution and it is too old (tox will complain). You can
48+
upgrade it individually, if you need to::
49+
50+
pip3 install -U virtualenv --user
51+
52+
Running Unit Tests Locally
53+
==========================
54+
55+
If you haven't already, python-gitlab source code should be pulled directly from git::
56+
57+
# from your home or source directory
58+
cd ~
59+
git clone https://github.com/python-gitlab/python-gitlab
60+
cd python-gitlab
61+
62+
Running Unit and Style Tests
63+
----------------------------
64+
65+
All unit tests should be run using tox. To run python-gitlab's entire test suite::
66+
67+
# to run the py3 unit tests, and the style tests
68+
tox
69+
70+
To run a specific test or tests, use the "-e" option followed by the tox target
71+
name. For example::
72+
73+
# run the unit tests under py310 (Python 3.10) and also run the pep8 tests
74+
tox -e py310,pep8
75+
76+
You may pass options to the test programs using positional arguments.
77+
To run a specific unit test, this passes the desired test
78+
(regex string) to `pytest <https://docs.pytest.org/en/latest/>`_::
79+
80+
# run tests for Python 3.8 which match the string 'test_projects'
81+
tox -e py310 -- -k test_projects
82+
83+
Additional Tox Targets
84+
----------------------
85+
86+
There are several additional tox targets not included in the default list, such
87+
as the target which builds the documentation site. See the ``tox.ini`` file
88+
for a complete listing of tox targets. These can be run directly by specifying
89+
the target name::
90+
91+
# generate the documentation pages locally
92+
tox -e docs

‎docs/contributor/index.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. python-gitlab documentation master file, created by
2+
sphinx-quickstart on Mon Dec 8 15:17:39 2014.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Developer's Guide
7+
=================
8+
9+
Contents:
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
14+
Developer Contribution Guide <contributing>
15+
Setting Up Your Development Environment <dev-quickstart>
16+
17+
18+
Indices and tables
19+
==================
20+
21+
* :ref:`genindex`
22+
* :ref:`modindex`
23+
* :ref:`search`

‎docs/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Contents:
1818
api-objects
1919
api/gitlab
2020
cli-objects
21+
contributor/index
2122
changelog
2223
release-notes
2324

0 commit comments

Comments
 (0)