Skip to content

Latest commit

 

History

History
290 lines (197 loc) · 9.98 KB

CONTRIBUTING.rst

File metadata and controls

290 lines (197 loc) · 9.98 KB
Raw

Contributing to Socon

We would highly appreciate any kind of contribution to the project. As the project is still as its premise we need more people than ever. You can contribute to Socon in many ways by fixing bugs, writing docs, proposing new features and many more. Every little bit helps!

Contents

Writing code

Whether you're fixing bugs or writing new features, you will need to write codes. Socon follow specific coding rules that you can retrieve in the :doc:`coding-style` documentation.

Features

New features

We would really like to hear your suggestions. Feel free to submit them as issues and:

  • Explain in detail your suggestions and how it works
  • If anything in the project is impacted, explain how and why?
  • Keep it simple!

Implement features

Look through the Github issues for enhancements. Send an email to socon-dev@proton.me or use the Socon GitHub discussion to find out how you can implement this feature. To indicate that you are going to work on that particular feature, please add a comment to that effect on the specific enhancement.

Bugs

Report bugs

If you are not sure to have see a bug, ask in the Socon GitHub discussion.

You can report bugs for Socon in the issue tracker <https://github.com/socon-dev/socon/issues>. Be sure to integrate the following when you do so:

  • A detailed description of the bug or problem you are having. Well-written
    bug reports are incredibly helpful.
  • The operating system you are using and the version.
  • Minimum example on how to reproduce the issue.
  • The version of Socon you are using.

Fix bugs

Look through the GiHub issues for bugs. The same way you would implement a features, send an email to socon-dev@proton.me or use the Socon GitHub discussion to find out how you can implement this feature. To indicate that you are going to work on that particular bug, please add a comment to that effect on the specific issue.

Write documentation

Socon can always use more documentation. In some case the documentation might be unclear or incomplete. We need your to help fix that and make it better. If you have a writer's soul here is how you can help and what needs to get done:

  • Add complementary documentation. Is something unclear? Does it need
    more information?
  • Function, class, attributes docstrings. It is really important that the
    end-user get immediately what a function does without reading the documentation. Socon use the Sphinx docstring format.
  • Example, topics, how-to documentations are very appreciated.

Important

Socon does not use code docstring to populate the API's documentation. We think that too much information in a function description can make it unclear. We want docstring to be simple and straight-forward.

The documentation use Sphinx documentation system. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format.

To build the documentation locally you will have to install Sphinx:

$ python -m pip -r docs/requirements.txt

Then from the docs directory, build the html:

$ make html

The built documentation should be available in docs/_build/html.

How the documentation is organized

The documentation is organized into several categories:

  • :doc:`Tutorials </intro/tutorials/index>` take the reader by the hand through a
    series of basic to complex examples in order to create something. The important thing about a tutorials is to help the reader create something useful that will help him in the daily use of Socon.
  • :doc:`Reference guides </ref/index>` contain technical reference for API's.
    They describe how Socon's internal machinery functions. The important thing in the reference guides is to assume that the user already understands the basic concepts involved but needs a reminder on how Socon does it.
  • :doc:`How-to guides </how-to/index>` take the reader through steps in key
    subjects. The important aspect in that section is that each subject must be result-oriented rather than focused on internal details.

Spelling check

sphinxcontrib.spelling is a spelling checker for Sphinx. It uses PyEnchant to produce a report showing misspelled words. It is a good idea to run the tool before you commit your docs.

Then from the docs directory:

$ make spelling

Wrong words (if any) along with the file and line number where they occur will be saved to _build/spelling/output.txt.

Note

If you are sure that you are using a correct word -- add it to docs/spelling_wordlist.

Contribute

Contribution is done through pull request from your own Socon repository (fork). As a quick reminder, a pull request informs Socon's core development team about the changes that you have submitted. It will allow us to review the code and to make comment to discuss its potential modification or not.

Find below an example on how to fork Socon and make a pull request:

  1. Fork the Socon. If you don't know how to do it, check the GitHub documentation documentation.

  2. Open Git bash, and create your fork locally using git:

    $ git clone git@github.com:YOUR_GITHUB_USERNAME/socon.git
$ cd socon

  3. Create a branch from the master branch:

    $ git checkout -b your-branch master

  4. Add main Socon remote as upstream. This will help you synchronize your fork with the main repository.

    $ git remote add upstream https://github.com/socon-dev/socon

  5. Install pre-commit:

    $ pip install pre-commit
$ pre-commit install
$ pre-commit install --hook-type commit-msg

    Afterwards pre-commit will run whenever you commit.

    https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks to ensure code-style and code formatting is consistent.

  6. Install tox. This tool runs all the tests and will automatically setup a virtual environment to run the tests in:

    $ pip install tox

  7. Make your changes. Do not forget to follow the :doc:`coding rules <coding-style>`

  8. Run the tests + linting with tox:

    $ tox -e flake8,isort,black,py39

    This command will run tests via tox tool against python 3.9 and perform a lint coding style check using flake8

  9. In case you don't want to run the tests using tox you can do it manually. First create a :doc:`virtual environment </intro/environment>` then go to the tests directory and:

    $ python -m pip install -e ..
$ python -m pip install -r requirement/requirements.txt
$ pytest -v

  10. Create a new changelog entry in changelog directory. The file should be named <issueid>.<type>.rst, where issueid is the number of the issue related to the change and type is one of feature, improvement, bugfix, doc, deprecation, breaking, or trivial. You may skip creating the changelog entry if the change doesn't affect the documented behaviour of socon.

  11. Add yourself to AUTHORS file if not there yet, in alphabetical order.

  12. Commit and push once your tests pass and you are happy with your changes:

    $ git commit -m "[#ticket-id] <commit message>"
$ git push -u

    The ticket id that you are working on must be put in the commit message using [#ticket-id]

  13. Finally, submit your pull request through the GiHub website. When your pull request will be created, Socon will automatically tests your pull requests and let you know if everything is working.

Tests

Socon uses pytest to write and run tests. Socon comes with a test suite of its own, in the tests directory of the code base. It is mandatory that all tests pass at all times.

Quick installation guide

  1. Fork the Socon. If you don't know how to do it, check the GitHub documentation documentation.

  2. Create and activate a :doc:`virtual environment </intro/environment>`

  3. Open Git bash, clone your fork locally using git, install the requirements and run the tests:

    $ git clone git@github.com:YOUR_GITHUB_USERNAME/socon.git
$ cd socon/tests
$ python -m pip install -e ..
$ python -m pip install -r requirement/requirements.txt
$ pytest -v

Writing tests

When you write a test, we would love for you to follow couple rules:

  • Write tests before you write your functionality (TDD). Test-drive development.
    Write a test, make it run, change the code to make it right, repeat the process.
  • Keep tests short. It's easier to read and understand.
  • Use pytest fixture and don't repeat yourself.
  • Test one requirement at a time.
  • Look at what has been done before and use as example.

Code coverage

Socon should always be 100% covered. We encourage developers to always look if their changes are covered by tests. Coverage doesn't mean that there are no bugs but it helps build confidence in the project.

If you installed the above requirement, cd into Socon root directory and:

$ pytest --cov-report html --cov=socon tests/

This command will generate an html report in a coverage directory. From there you can check the index.html. This page display Socon coverage by modules.