Contributor Guide =================== Open Issues --------------------------------- The first way to contribute is to test the software and raise or open issues. Showyourwork issues can be found `in the github repo `_. The "contributions welcome" tag is a great place to start! Testing an existing pull request -------------------------------- You might have opened an issue or someone else might have, and a pull request (PR) has been opened to address it. You can test the PR by following these steps: if you did not clone the repository yet 1. ``git clone https://github.com/showyourwork/showyourwork.git`` find which is the correct remote name with ``git remote -v``, so you sure to fetch the remote branch from the real upstream repository and someone else's fork 2. ``git fetch`` now you should see the branch associated with the open PR, which should be named something like ``remote-name/branch-name`` 3. ``git switch branch-name`` now you have a local copy of the remote branch, and you can test it by installing _showyourwork_ in editable mode (just so you can switch branches later easily without having to reinstall) 4. ``pip install -e .`` now move to another directory where to test a new project 5. ``showyourwork setup -a git+https://github.com/showyourwork/showyourwork@branch-name foo/bar`` edit your new test project with what reproduces the bug 6. ``showyourwork build`` and then let's hope everything works as expected :) Contributing to the documentation --------------------------------- A great place to start contributing is to documentation. In order to do this you'll want to run the docs locally. Here are the steps for getting setup. .. _initial-setup: Initial setup ^^^^^^^^^^^^^ 1. `Fork `_ the |showyourwork| github repo and `clone `_ your forked repo locally 2. Create a conda environment for the docs Building the docs includes a few extra libraries that aren't required for |showyourwork| users, so its helpful to create a separate environment for those. You should only ever have to do this step once. The simplest way to get an environment is to first create it .. code-block:: bash conda create -n sywdocs python pip activate it .. code-block:: bash conda activate sywdocs and install showyourwork with the ``[docs]`` extra (if you plan on doing :ref:`code contributions`, you can replace ``[docs]`` with ``[dev]``). .. code-block:: bash python -m pip install -e ".[docs]" During development ^^^^^^^^^^^^^^^^^^ The remaining steps will be run every time you work on the documentation. 1. Activate the docs environment .. code-block:: text conda activate sywdocs 2. Go into the documentation folder .. code-block:: text cd docs 3. Create the html from the reStructured Text (``.rst``) files .. code-block:: text make html 4. Run a local file server of the docs website .. code-block:: text python3 -m http.server -d _build/html From here you can go to a web browser and open up the docs using the port shown in terminal. (Ex. ``localhost:8000``) The last two steps will need to be run every time you make a change in the ``.rst`` files and want to view them. Because of this it can be nice to run them together using .. code-block:: text make html && python3 -m http.server -d _build/html That's the setup! Open documentation issues can be perused `here `_ . .. _contributing-code: Contributing code ----------------- To contribute code, you will need to install showyourwork in development mode. The simplest way to do this is to follow the :ref:`initial-setup` instructions, but replace the ``[docs]`` extra with the ``[dev]`` extra. Then, follow these instructions to make your code contribution: 1. Start from an up-to-date branch of the main branch (name your branch something descriptive like 'fix-typo-in-docs' or 'add-new-feature') .. code-block:: sh git switch main git pull upstream main # here 'upstream' is the original repo remote name, NOT your fork git switch -c my-feature-branch 2. Make your changes trying to make small well-defined commits with descriptive messages (this will make it easier to review and understand the changes) and following the project's coding style 2. Open a pull request against the main branch of the original repo 3. Add a news fragment in the ``docs/changes`` directory This is required for all PRs. The news fragment should be a file named ``..rst``, ```` is one of the following: - ``bugfix``: for bug fixes - ``feature``: for new features - ``maintenance``: for maintenance tasks, like updating dependencies or documentation - ``api``: for changes to the public API - ``optimization``: for changes that improve performance or refactor code , but do not change user experience Making a new release -------------------- To generate the changelog before a new release, execute the following command in the base directory of the project .. code-block:: sh towncrier build --version= This will update and stage the CHANGES.rst file with the new release information, removing the existing news fragments from the ``docs/changes`` directory. You can then prepare a new PR with the title "Prepare release X.Y.Z" which should be merged before proceeding the release. TODO: Review instructions to actually make a new release. Add new templates ----------------- To add a new template to the list of available templates, you need to: 1. create a new template repository (please, make sure it works and it is up to date) 2. transfer the new template to the list of available templates under the _showyourwork_ organization (please, contact the administrators in case you do not have sufficient permissions) 3. add a link to the new template repository in the :ref:`templates` section of the documentation (start by copy-pasting an existing card entry and customize it for your use case)