On your computer, you need to install:
- Python 3.8
- Poetry
- Nox
- nox-poetry
Refer to the instructions that correspond to your OS.
Fork the repository (use the fork button on Source Code) and then clone the forked repository.
Either from command-line:
$ git clone https://github.com/<your_username>/track-viz.git
$ cd track-viz
$ git remote add upstream https://github.com/JulienMBABD/track-viz.git
or from the IDE you are using (Pycharm, VSCode, ...).
Use the command line to install all needed packages for development:
$ poetry install
This will create a new virtual Python environment that will include:
- Python 3.8
nox
,poetry
- All dependencies (
pandas
, etc...) of the module - All development tools (
ipython
,jupyter-lab
,black
, ...) - The module
track-viz
itself, in editable mode
Note the name of the virtual environment (something like track-viz-xxxxxxxx-py3.8
).
Register in your IDE project the corresponding Python executable as the Python interpreter.
Enter the virtual environment:
$ poetry shell
Starting from now, the virtual environment is active. Any change done to the source code of the module will be immediatly available in the shell.
Call the module with:
$ track-viz gpx-to-csv --gpx <file> --to <csvfile>
Any change on the source code is immediatly applied and can be observed by launching a command similar to the previous one.
For the list of commands, refer to Usage
Install the pre-commit hooks (more on this later):
$ pre-commit install
Everything is called an issue, but actually the same word is used to indicate:
- Bug reports (something does not work the way it should, it crashes with some datafiles...)
- Idea of new features (the program could do something else, a new visualization, ...)
- Code Refactoring (do the same, but with better code, maybe a better library to handle visualizations...)
Pick up one issue from the Issue Tracker, or create a new one.
Use the issue comments to indicate your interest, claim one issue for yourself.
Update your local copy of the repository, update your fork with the latest version:
$ git checkout main
$ git pull upstream
$ git push
Create a new branch, using the issue number in the name (here 372):
$ git checkout -b issue-372
All of this can be done from your IDE, just make sure you are starting a new branch from the most up-to-date version of the repository on the MAIN branch, and you are working on this new branch.
Change all needed files, write new functions, create new files, etc...
A new library needs to be used, for example altair
. It has to be added to the list of dependencies of the module:
$ poetry add altair
A few modifications have been made, it is time to commit them, using either command line or the IDE.
This happens within the new branch issue-xxx
:
$ git add .
$ git commit
This will launch the pre-commit hooks. They are programs that will be launched every time there is a commit.
Each program checks something on the project's source code, and one of the programs failing is enough to refuse the commit until the checks are satisfied:
black
will take care of formatting the source codeflake8
will check code rules (no unused variable, no unused import, ...)
Some of the checks can modify the files to make them compliant (black
), others will require you make modifications
(flake8
).
After modification:
$ git add .
$ git commit
After all is OK, the commit is accepted. Push it to the repository:
$ git push --set-upstream origin issue-xxx
Visit the webpage of the YOUR repository fork and create a Pull Request from your new branch issue-xxx
. There are
instructions available on `Github Website<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_,
or on the Internet.
Mention the issue in the Pull Request, using #xxx
where xxx
is the issue number.
This will launch a battery of tests through github actions. The results will be either OK or Not OK.
Unfortunately, it is likely the github action will return a negative result. You can check this on your own computer.
Run the existing unit tests:
$ nox -r -s tests --python=3.8
Fix any failing unit test, and do a new commit/push only when the tests are OK.
ADD NEW TESTS to proove bugfixing was ok, or to proove a new functionality does work.
Unit tests are located in the tests
directory,
and are written using the pytest testing framework.
mypy
takes care that all the code is properly typed:
- all functions carry type hinting for arguments and return
- all variables have type-hints that correspond to their values
It is very strict, look for help if you can't find a solution.
Cycle again on modifying, commiting, pushing in the branch.
Every new commit to the branch is detected by the pull request automatically, and will launch the test battery again.
All the checks are OK, there are new tests in place... it's ready for review. From the pull request, ask a review, a maintainer will take care of reviewing one last time the changes, maybe ask some additions, or some code modifications, and merge the modifications in the main branch.
Thank you for your interest in improving this project. This project is open-source under the MIT license and welcomes contributions in the form of bug reports, feature requests, and pull requests.
Here is a list of important resources for contributors:
Report bugs on the Issue Tracker.
When filing an issue, make sure to answer these questions:
- Which operating system and Python version are you using?
- Which version of this project are you using?
- What did you do?
- What did you expect to see?
- What did you see instead?
The best way to get your bug fixed is to provide a test case, and/or steps to reproduce the issue.
Request features on the Issue Tracker.