Here we explain how to contribute to a project that adopted this template. Actually, you can use this same scheme when contributing to this template. If you are completely new to git
this might not be the best beginner tutorial, but will be very good still ;-)
You will notice that the text that appears is a mirror of the CONTRIBUTING.rst
file. You can also point your community to that file (or the docs) to guide them in the steps required to interact with you project.
Contributing¶
How to contribute to this project.
Fork this repository¶
Fork this repository before contributing.
Clone your fork¶
Next, clone your fork to your local machine, keep it up to date with the upstream, and update the online fork with those updates.
git clone https://github.com/YOUR-USERNAME/libfuncpy.git
cd libfuncpy
git remote add upstream git://github.com/joaomcteixeira/libfuncpy.git
git fetch upstream
git merge upstream/main
git pull origin main
Install for developers¶
Create a dedicated Python environment where to develop the project.
If you are using pip
follow the official instructions on
Installing packages using pip and virtual environments, most likely
what you want is:
python3 -m venv libfuncpy
source libfuncpy/bin/activate
If you are using Anaconda go for:
conda create --name libfuncpy python=3.7
conda activate libfuncpy
Where libfuncpy
is the name you wish to give to the environment
dedicated to this project.
Either under pip or conda, install the package in develop
mode, and also tox. Note, here I
assume our project has no dependencies.
python setup.py develop
pip install tox
This configuration, together with the use of the src
folder layer,
guarantee that you will always run the code after installation. Also,
thanks to the develop
flag, any changes in the code will be
automatically reflected in the installed version.
Make a new branch¶
From the main
branch create a new branch where to develop the new code.
git checkout main
git checkout -b new_branch
Develop the feature and keep regular pushes to your fork with comprehensible commit messages.
git status
git add (the files you want)
git commit -m (add a nice commit message)
git push origin new_branch
While you are developing, you can execute tox
as needed to run your
unittests or inspect lint, etc. See the last section of this page.
Update CHANGELOG¶
Update the changelog file under docs/CHANGELOG.rst
with an
explanatory bullet list of your contribution. Add that list right after
the main title and before the last version subtitle:
Changelog
=========
* here goes my new additions
* explain them shortly and well
vX.X.X (1900-01-01)
-------------------
Also add your name to the authors list at docs/AUTHORS.rst
.
Pull Request¶
Once you are finished, you can Pull Request you additions to the main
repository, and engage with the community. Please read the
PULLREQUEST.rst
guidelines first, you will see them when you open a
PR.
Before submitting a Pull Request, verify your development branch passes all tests as described bellow . If you are developing new code you should also implement new test cases.
Uniformed Tests with tox¶
Thanks to Tox we can have a unified testing platform where all developers are forced to follow the same rules and, above all, all tests occur in a controlled Python environment.
With Tox, the testing setup can be defined in a configuration file,
the tox.ini, which contains all the operations that are performed
during the test phase. Therefore, to run the unified test suite,
developers just need to execute tox
, provided tox is installed in
the Python environment in use.
pip install tox
# or
conda install tox -c conda-forge
Before creating a Pull Request from your branch, certify that all the tests pass correctly by running:
tox
These are exactly the same tests that will be performed online in the Github Actions.
Also, you can run individual environments if you wish to test only specific functionalities, for example:
tox -e lint # code style
tox -e build # packaging
tox -e docs # only builds the documentation
tox -e prreqs # special requirements before Pull Request
tox -e py37 # performs pytest in Python 3.7 environment (it should
be installed)