|
| 1 | +Contribution guide |
| 2 | +================== |
| 3 | + |
| 4 | +Setting up the environment |
| 5 | +-------------------------- |
| 6 | + |
| 7 | +1. Install `PDM <https://pdm.fming.dev/latest/>`_ |
| 8 | +2. Run ``pdm install -G:all`` to create a `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_ and install |
| 9 | + the dependencies |
| 10 | +3. If you're working on the documentation and need to build it locally, install the extra dependencies with ``pdm install -G:docs`` |
| 11 | +4. Install `pre-commit <https://pre-commit.com/>`_ |
| 12 | +5. Run ``pre-commit install`` to install pre-commit hooks |
| 13 | + |
| 14 | +Code contributions |
| 15 | +------------------ |
| 16 | + |
| 17 | +Workflow |
| 18 | +++++++++ |
| 19 | + |
| 20 | +1. `Fork <https://github.com/cofin/litestar-vite/fork>`_ the `Advanced Alchemy repository <https://github.com/cofin/litestar-vite>`_ |
| 21 | +2. Clone your fork locally with git |
| 22 | +3. `Set up the environment <#setting-up-the-environment>`_ |
| 23 | +4. Make your changes |
| 24 | +5. (Optional) Run ``pre-commit run --all-files`` to run linters and formatters. This step is optional and will be executed |
| 25 | + automatically by git before you make a commit, but you may want to run it manually in order to apply fixes |
| 26 | +6. Commit your changes to git |
| 27 | +7. Push the changes to your fork |
| 28 | +8. Open a `pull request <https://docs.github.com/en/pull-requests>`_. Give the pull request a descriptive title |
| 29 | + indicating what it changes. If it has a corresponding open issue, the issue number should be included in the title as |
| 30 | + well. For example a pull request that fixes issue ``bug: Increased stack size making it impossible to find needle #100`` |
| 31 | + could be titled ``fix(#100): Make needles easier to find by applying fire to haystack`` |
| 32 | + |
| 33 | +.. tip:: Pull requests and commits all need to follow the |
| 34 | + `Conventional Commit format <https://www.conventionalcommits.org>`_ |
| 35 | + |
| 36 | +Guidelines for writing code |
| 37 | +---------------------------- |
| 38 | + |
| 39 | +- All code should be fully `typed <https://peps.python.org/pep-0484/>`_. This is enforced via |
| 40 | + `mypy <https://mypy.readthedocs.io/en/stable/>`_. |
| 41 | +- All code should be tested. This is enforced via `pytest <https://docs.pytest.org/en/stable/>`_. |
| 42 | +- All code should be properly formatted. This is enforced via `black <https://black.readthedocs.io/en/stable/>`_ and `Ruff <https://beta.ruff.rs/docs/>`_. |
| 43 | + |
| 44 | +Writing and running tests |
| 45 | ++++++++++++++++++++++++++ |
| 46 | + |
| 47 | +.. todo:: Write this section |
| 48 | + |
| 49 | +Project documentation |
| 50 | +--------------------- |
| 51 | + |
| 52 | +The documentation is located in the ``/docs`` directory and is `ReST <https://docutils.sourceforge.io/rst.html>`_ and |
| 53 | +`Sphinx <https://www.sphinx-doc.org/en/master/>`_. If you're unfamiliar with any of those, |
| 54 | +`ReStructuredText primer <https://www.sphinx-doc.org/en/master/lib/usage/restructuredtext/basics.html>`_ and |
| 55 | +`Sphinx quickstart <https://www.sphinx-doc.org/en/master/lib/usage/quickstart.html>`_ are recommended reads. |
| 56 | + |
| 57 | +Running the docs locally |
| 58 | +++++++++++++++++++++++++ |
| 59 | + |
| 60 | +To run or build the docs locally, you need to first install the required dependencies: |
| 61 | + |
| 62 | +``pdm install -G:docs`` |
| 63 | + |
| 64 | +Then you can serve the documentation with ``make docs-serve``, or build them with ``make docs``. |
| 65 | + |
| 66 | +Creating a new release |
| 67 | +---------------------- |
| 68 | + |
| 69 | +1. Increment the version in `pyproject.toml <https://github.com/cofin/litestar-vite/blob/main/pyproject.toml>`_. |
| 70 | + .. note:: The version should follow `semantic versioning <https://semver.org/>`_ and `PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_. |
| 71 | +2. `Draft a new release <https://github.com/cofin/litestar-vite/releases/new>`_ on GitHub |
| 72 | + |
| 73 | + * Use ``vMAJOR.MINOR.PATCH`` (e.g. ``v1.2.3``) as both the tag and release title |
| 74 | + * Fill in the release description. You can use the "Generate release notes" function to get a draft for this |
| 75 | +3. Commit your changes and push to ``main`` |
| 76 | +4. Publish the release |
| 77 | +5. Go to `Actions <https://github.com/cofin/litestar-vite/actions>`_ and approve the release workflow |
| 78 | +6. Check that the workflow runs successfully |
0 commit comments