Skip to content

How to get started? How to contribute?

Remember to keep things as simple, as minimal and as usable as possible (see the suckless philosophy).


Code of conduct

See the Python Code Quality Authority’s Code of Conduct.


Prerequistes

Git

The versionning system used for this project is Git (via the GitLab Git server), which is a free and open source distributed version control system.

You can install Git, and learn more about it, by following its official documentation.

Note: When commiting with Git, while working on the SARAR project, whenever possible please refer to the issue you are working on (e.g. add see #42 at the end of your commit if you are working on issue number 42).

Python 3

The programming language used to develop SARAR is Python.

If you are discovering Python: you can follow the Getting Started guide, in order to install it and learn more about it.

If you are wondering what is the "Python philosophy" of doing things in this project, then I suggest you read this excellent series of articles.

Poetry

The Python package/environment manager used for this project is poetry.

You can install poetry, and learn more about it, by following its [official documentation]((https://python-poetry.org/docs/).

For example, here is how I installed it:

  • First, define a poetry home:

    $ vi $HOME/.bashrc # or ~/.zshrc or ~/.zshenv or wherever
        > ...
      + >
      + > # PYTHON POETRY
      + > export POETRY_HOME="${XDG_DATA_HOME:-${HOME/.local/share}}/poetry"
      + > export PATH="$POETRY_HOME/bin:$PATH"
    
    $ source $HOME/.bashrc # or ~/.zshrc or ~/.zshenv or wherever
    

  • Then install it, without automatically modifing your path:

    $ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py > get-poetry.py
    $ python get-poetry.py --no-modify-path
    

  • Now, make sure poetry is up to date:

    $ poetry self update
    $ poetry --version
    

  • Optionally, you might want to create a virtual environment per project inside the project's root directory. If so, the virtual environment will be created and expected in a folder named .venv:

    $ poetry config virtualenvs.in-project true
    

  • If you want to uninstall poetry:

    $ python get-poetry.py --uninstall
    


How to install, update and run

  • Installing the project and all its developpement dependencies is quite simple:

    $ git clone https://gitlab.com/stephane.tzvetkov/sarar.git
    $ cd sarar
    $ poetry install
    

  • Updating it is even more easy:

    $ git pull
    

  • Running it just requires to execute the following:

    $ poetry run sarar
    

  • E.g. if you want to run the check-deck command:

    $ poetry run sarar check-deck -d /path/to/deck.deck
    


Coding style

In order to save time and mental energy for more important matters, black is the tool used in this project to format Python code.

black enforces formatting that conforms to PEP 8 which is a very sane style guide for Python (and a very interesting reading).


Linting

The linters used for this project are flake8 and pylint, because they are well supported by black (see black compatible configurations).

  • flake8 is a popular lint wrapper for python. Under the hood, it runs three other tools and combines their results:

  • pylint is also a popular linter for python (now it even is the default python linter in VS Code). Under the hood, it runs those tools to combine their results:

    • astroid for a base representation of python source code
    • isort for imports management
    • mccabe for checking complexity

Here are some resources in order to integrate flake8 to your IDE:

Here are some resources in order to integrate pylint to your IDE:


Debug

If you encounter tough errors during your developments, do not hesitate to use the Python debugger.

If you want to check your PYTHONPATH you can use some of those commands:

$ poetry run python -m site
$ poetry run bash -c "echo $PATH"
$ poetry run python -c "import sys, pprint; pprint.pprint(sys.path)"


Tests

The test framework used for this project is pytest.

Pytest has already been installed in your virtual environment when running $ poetry install, you can learn more about it by reading its official documentation.

When adding, changing or removing some code to the SARAR project, make sure to update the tests accordingly. And of course: make sure the tests are successful!

So, before pushing any new code, please check the results of the following tests:

$ poetry run pytest # run tests
$ poetry run pytest -v -r a # run tests with better looking output
$ poetry run pytest --black  # check black formatting
$ poetry run pytest --flake8 # check flake8 linter
$ poetry run pytest --pylint # check pylint linter
You can also test all at once with this one-liner:
$ poetry run pytest -v -r a --black --flake8 --pylint

SARAR uses the Click module in order to create command line interfaces, here is how to create tests against Click-based apps: https://click.palletsprojects.com/en/7.x/testing/?highlight=testing

Note that you can also check the code coverage with the following command:

$ poetry run pytest --cov=sarar --cov-report html

This will generate the ./htmlcov folder. You can open it in your browser, e.g. with firefox: $ firefox ./htmlcov/index.html, and check your coverage.

This will also generate a .coverage file used to create the coverage badge. You can create/update the coverage badge with the following command:

$ poetry run coverage-badge -o .coverage.svg


Documentation

When adding, changing or removing some code to the SARAR project, make sure to update accordingly the associated docstring and the documentation folder (docs at the root of the project). Feel free to create, update or delete any file, and eventually reference it from the README.

Markdown documentation

When documenting in the README or the docs folder, please respect the markdown syntax in order to get nice and pleasant files to read.

The docs folder is also the root directory for mkdocs to work, mkdocs is a documentation-oriented site generator: it will build a static HTML site from the markdown file and will allow to format the documentation in a very nice way.

So, once you are done editing, please build the documentation and serve it, in order to check it:

$ poetry run mkdocs serve -f .mkdocs.yaml
    > ...
    > Serving on http://127.0.0.1:8000
    > ...
Now just open http://127.0.0.1:8000 in a web-browser and make sure the rendering of your modifications is OK.

In another console, in order to make sure your documentation does not contains any broken link, you can run the following:

$ poetry run linkchecker --check-extern --ignore-url=https://gitlab.com/stephane.tzvetkov/sarar/edit/ --ignore-url=https://fonts --ignore-url=https://sci-hub.st/ --no-robots http://127.0.0.1:8000

Note that the static HTML site build by mkdocs is hosted on readthedocs, so after pushing your markdown modifications readthedocs will serve them here.

Docstring documentation

Also, when adding or changing some code functions, make sure to create or update their associated docstring. The docstring format used in this project is the one recommanded by the PEP 287, i.e. reStructuredText plaintext markup syntax. For a quick overview: see this example, or this one, or this one.

Help documentation / Command documentation

The documentation of this project contains a little specificity: the Markdown docs in the commands folder (e.g. the check-deck doc) are parsed by SARAR when printing help information in the command line (e.g. $ sarar check-deck --help).

This trick is possible thanks to the doc_to_help(...) function in sarar.py. So when creating or modifing a command doc, please check the Markdown rendering and the associated -h, --help option output (e.g. $ poetry run sarar check-deck --help).

Do not hesitate to change the doc_to_help(...) function according to your needs.

Note: the target format of a help-documentation / command-documentation is to be like a man page. Take inspiration from $ man man or $ man git.


Dependencies

You can check all the dependency tree of SARAR by running $ poetry show --tree, a short description for the top level dependencies will also be printed.

An other way to quickly check the top-dependencies of SARAR is to read the ./pyproject.toml file.


Release checklist

When a new version of SARAR is about to be released, make sure that:

  • the milestone of the new release has been completed (all associated issues must have been done and closed).

  • the dependencies have been updated

    $ poetry update
    

  • all the tests are passing

    $ poetry run pytest -v -r a --black --flake8 --pylint
    

  • the code coverage has been updated (TODO: run this into CI, not here manually)

    $ rm .badge_coverage.svg
    $ poetry run pytest --cov=sarar
    $ poetry run coverage-badge -o .badge_coverage.svg
    $ rm .coverage
    

  • the pylint score has been updated (TODO: run this into CI, not here manually)

    $ rm .badge_pylint.svg
    $ poetry run pylint --verbose --output-format=text sarar/ tests/ | tee .pylint.log
    $ PYLINT_SCORE=$(sed -n 's/^Your code has been rated at \([-0-9.]*\)\/.*/\1/p' .pylint.log)
    $ poetry run anybadge --label=pylint --file=.badge_pylint.svg --value=$PYLINT_SCORE/10 2=red 4=orange 8=yellow 10=green
    $ rm .pylint.log
    

  • TODO: the size badge has been updated (TODO: run this into CI, not here manually)

    $ SIZE=$(du -c --exclude=TODO --exclude=TODO | tail -1 | awk '{print $1}')
    $ curl https://img.shields.io/badge/repo%20size-$SIZE-informational -o .size.svg
    

  • the documentation has been updated and is looking nice

    $ poetry run mkdocs serve -f .mkdocs.yaml
    $ poetry run linkchecker --check-extern --ignore-url=https://gitlab.com/stephane.tzvetkov/sarar/edit/ --ignore-url=https://fonts --ignore-url=https://sci-hub.st/ --no-robots http://127.0.0.1:8000
    

  • the change log has been updated

  • the project layout has been updated

  • the __version__ variable in sarar.py has been updated

  • the build status has been updated (TODO: run this into CI, not here manually)

    $ rm .badge_build.svg
    $ poetry build
    $ BUILD_CODE="$?"
    $ if [ $BUILD_CODE -eq "0" ]; then BUILD_STATUS="passing"; else BUILD_STATUS="falling"; fi
    $ poetry run anybadge --label=build --file=.badge_build.svg --value=$BUILD_STATUS failling=red passing=green
    

  • the locally build version is running without problems:

    $ poetry build
    $ cd /tmp
    $ python -m venv test_venv
    $ . ./test_venv/bin/activate
    $ pip install --upgrade pip
    $ pip install /path/to/sarar/dist/sarar-0.1.0.tar.gz
    $ sarar
    $ # now check your developments
    $ deactivate
    $ rm -r test_venv
    

  • the milestone of the next release has been created.

  • the poetry poetry version has been updated (see here for more details, note that you can print the current version with $ poetry version):

    • in case of a major version bump: $ poetry version major (e.g. 1.3.0 -> 2.0.0)
    • in case of a minor version bump: $ poetry version minor (e.g. 2.1.4 -> 2.2.0)
    • in case of a patch version bump: $ poetry version patch (e.g. 4.1.1 -> 4.1.2)
  • TODO: the new poetry version has been published to PyPi: $ poetry publish