|
| 1 | +============ |
| 2 | +Contributing |
| 3 | +============ |
| 4 | + |
| 5 | +Thank you for your interest in contributing to this project! |
| 6 | + |
| 7 | +The following is a set of guidelines for contributing to this project. |
| 8 | +These are just guidelines, not rules. |
| 9 | + |
| 10 | +Ways You Can Contribute |
| 11 | +======================= |
| 12 | + |
| 13 | +The ways you can contribute are not only limited to code changes, but so much more. |
| 14 | +Some of the ways you can contribute are: |
| 15 | + |
| 16 | +- Reporting a bug |
| 17 | +- Discussing the current state and future of the project |
| 18 | +- Submitting a fix |
| 19 | +- Proposing new features |
| 20 | +- Improving or editing documentation |
| 21 | + |
| 22 | +Note that if you plan on proposing new features, please first discuss them with the project owners on the issues page. |
| 23 | + |
| 24 | +Writing Good Bug Reports |
| 25 | +======================== |
| 26 | + |
| 27 | +Please be aware of the following when you submit a bug report: |
| 28 | + |
| 29 | +1. Ask on the server first (this is preferred). If you are unsure about an issue, please contact the dev lead (Noelle) for clarification. |
| 30 | +2. Don't open duplicate issues. Please search your issue to see if it has been asked already. Duplicate issues will be closed. |
| 31 | +3. When filing a bug about exceptions or tracebacks, please include the complete traceback. Without the complete traceback the issue might be unsolvable and you will be asked to provide more information. |
| 32 | + |
| 33 | +If a bug report is not clear enough, or missing these information, then more than likely |
| 34 | +it'll take longer to fix the bug, or it'll be closed. More than likely clarification will |
| 35 | +be asked in order to aid in this process. |
| 36 | + |
| 37 | +Submitting Code |
| 38 | +=============== |
| 39 | + |
| 40 | +Submitting code is done through pull requests. Please ensure that the pull request |
| 41 | +focuses on a single aspect and doesn't leave the scope of that aspect. You'll have to |
| 42 | +keep in mind about the following guidelines when submitting code. |
| 43 | + |
| 44 | +Programming Style |
| 45 | +----------------- |
| 46 | + |
| 47 | +In order to keep the code unified, `Black <https://github.com/psf/black>`_, `AutoFlake <https://github.com/PyCQA/autoflake>`_, and |
| 48 | +`Isort <https://github.com/PyCQA/isort>`_ are used to format code to a consistent style. |
| 49 | +In addition, linters such as `Pyright <https://github.com/microsoft/pyright>`_ and `Ruff <https://github.com/astral-sh/ruff>`_ are |
| 50 | +used to ensure that code quality is kept to its standards and properly type hinted. The formatters are ran automatically within a pre-commit |
| 51 | +hook, which is ran before every commit. If you wish to run the pre-commit hook manually, you can run the following command: |
| 52 | + |
| 53 | +.. code-block:: bash |
| 54 | +
|
| 55 | + pre-commit run --all-files |
| 56 | +
|
| 57 | +.. note:: |
| 58 | + |
| 59 | + This project does follow the guidelines of `PEP-8 <https://peps.python.org/pep-0008/>`_ strictly. Please ensure that |
| 60 | + your code is in accordance with PEP-8. |
| 61 | + |
| 62 | +Static Code Analyzers |
| 63 | +--------------------- |
| 64 | + |
| 65 | +In addition to the tools mentioned, `SonarCloud <https://sonarcloud.io/>`_ is also used to analyze the codebase. |
| 66 | +If there is a issue raised by SonarCloud, please fix it. If you are unsure about the issue, |
| 67 | +please contact the dev lead (Noelle) for clarification. |
| 68 | + |
| 69 | +Pull Request Details |
| 70 | +-------------------- |
| 71 | + |
| 72 | +Source Control Branching Model |
| 73 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 74 | + |
| 75 | +.. figure:: /_static/assets/trunk-workflow.svg |
| 76 | + :alt: Trunk Based Development Workflow |
| 77 | + :align: center |
| 78 | + |
| 79 | +The model used for source control branching is `trunk-based <https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development>`_. |
| 80 | +The ``main`` branch is known to contain working code, and thus cannot be touched directly. |
| 81 | + |
| 82 | +.. _Branch Naming Convention: |
| 83 | + |
| 84 | +Branch Naming Convention |
| 85 | +^^^^^^^^^^^^^^^^^^^^^^^^ |
| 86 | + |
| 87 | +When you create a branch, please use the following naming convention: |
| 88 | + |
| 89 | +.. code-block:: |
| 90 | +
|
| 91 | + <name>/<type> |
| 92 | +
|
| 93 | +
|
| 94 | +``<name>`` is your name (you can use your GitHub name) and ``<type>`` is a concise one to three word description of the branch. |
| 95 | +For example, if a pull request has the name ``noelle/docs``, this indicates that the branch is created and owned by Noelle, |
| 96 | +and the purpose of the branch is to update documentation. |
| 97 | + |
| 98 | +Pull Request Checklist |
| 99 | +^^^^^^^^^^^^^^^^^^^^^^ |
| 100 | + |
| 101 | +When you create a pull request, please ensure that the following is done: |
| 102 | + |
| 103 | +1. Ensure that you have forked the repository and created a branch from ``main`` with the correct naming conventions as mentioned :ref:`above <Branch Naming Convention>`. |
| 104 | +2. Make sure that you have noted the changes in the ``changelog.md`` file. |
| 105 | +3. Your code is properly formatted and linted (and all workflows are passing). |
| 106 | + |
| 107 | +Git Commit Guidelines |
| 108 | +--------------------- |
| 109 | + |
| 110 | +1. Use present tense and imperative mood when writing commit messages. For example, ``Add new feature`` instead of ``Added new feature``. |
| 111 | +2. Reference issues or pull requests outside of the first line. |
| 112 | + a. Please use the shorthand ``#123`` and not the full URL. |
| 113 | +3. Commits that need to skip the CI workflows must be prefixed with ``[skip ci]``. |
0 commit comments