Contributor Guide

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

  1. git fetch

now you should see the branch associated with the open PR, which should be named something like remote-name/branch-name

  1. 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)

  1. pip install -e .

now move to another directory where to test a new project

  1. showyourwork setup -a git+https://github.com/showyourwork/showyourwork@branch-name foo/bar

edit your new test project with what reproduces the bug

  1. 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#

  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

conda create -n sywdocs python pip

activate it

conda activate sywdocs

and install showyourwork with the [docs] extra (if you plan on doing code contributions, you can replace [docs] with [dev]).

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

conda activate sywdocs

  1. Go into the documentation folder

cd docs

  1. Create the html from the reStructured Text (.rst) files

make html

  1. Run a local file server of the docs website

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

make html && python3 -m http.server -d _build/html

That’s the setup! Open documentation issues can be perused here .

Contributing code#

To contribute code, you will need to install showyourwork in development mode. The simplest way to do this is to follow the 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’)

git switch main
git pull upstream main # here 'upstream' is the original repo remote name, NOT your fork
git switch -c my-feature-branch

  1. 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

  1. Open a pull request against the main branch of the original repo

  2. Add a news fragment in the docs/changes directory

    This is required for all PRs. The news fragment should be a file named <pull_request_number>.<type>.rst, <type> 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

towncrier build --version=<VERSION NUMBER>

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 Templates section of the documentation (start by copy-pasting an existing card entry and customize it for your use case)