Hackathon git workflow practice

[martinjrobins]

Background

On the 17th April 2024 we are holding the next PyBaMM hackathon at the Mathematical Institute at the University of Oxford. In order for attendees to become familar with the process of contributing code to PyBaMM, we have created this issue to inform new contributors and give them some practice at contributing a relatively small fix to the PyBaMM codebase.

The next section summarises the process of contributing code to PyBaMM. The last section points towards a number of issues that would be suitable for first time contributors, here we are focusing on issues relating to the PyBaMM documentation rather than functionality / bug fixes, but please feel free to branch out if you wish. The goal is for each hackathon attendee to pick an issue to work on, complete it, create a PR and (ideally) have it merged into the develop branch before the hackathon. Please note that it might take a few weeks for your PR to be reviewed and merged, so please start this process as early as possible.

How to contribute to PyBaMM

This is a summary of parts of the CONTRIBUTING.md document most relevent to this issue. Please see CONTRIBUTING.md for more details.

We use git and GitHub to coordinate our work. The OxRSE group maintain Git, and Github introductory courses that you are able to work through if you are unfamiliar with either of these.

The workflow for starting an issue, completing it and getting it merged into PyBaMM is as follows:

A. Before you begin

• Create an issue. For the hackathon practice we recommend taking on an already existing issue, which are linked in the section below.
• Create a branch of this repo (ideally on your own fork), where all changes will be made.
• Download the source code onto your local system, by cloning the repository (or your fork of the repository). After cloning make sure you swap to your new branch that you have created.
• Install PyBaMM with the developer options.
• Test if your installation worked, using the test script: $ python run-tests.py --unit.
  You now have everything you need to start making changes!

B. Writing your code

The issues recommended for the hackathon practices are all documentation issues, so no actual Python coding will be required. However, if you do choose another issue please see the CONTRIBUTING.md for relevent details.

We use Sphinx to take the docstrings on classes, member functions and modules and generate a set of API docs. Each docstring is written in the Numpy format, detailing important features of methods such as parameters, return types and if it raises any exceptions. The text of each docstring is written using markdown, and in particular Sphinx uses reStructuredText (reST), and you can find a reference for this here

To test and debug the documentation, it's best to build it locally. To do this, navigate to your PyBaMM directory in a console, and then type (on GNU/Linux, macOS, and Windows):

nox -s docs

And then visit the webpage served at http://127.0.0.1:8000. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded. In CI, the docs are built and tested using the docs session in the noxfile.py file with warnings turned into errors, to fail the build. The warnings can be removed or ignored by adding the appropriate warning identifier to the suppress_warnings list in docs/conf.py.

Commit your changes to your branch with useful, descriptive commit messages: Remember these are publicly visible and should still make sense a few months ahead in time. While developing, you can keep using the GitHub issue you're working on as a place for discussion. Refer to your commits when discussing specific lines of code.

C. Merging your changes with PyBaMM

When you feel your code/docstrings are finished, or at least warrants serious discussion, run the pre-commit checks and then create a pull request (PR) on PyBaMM's GitHub page.

Once a PR has been created, it will be reviewed by any member of the community. Changes might be suggested which you can make by simply adding new commits to the branch. When everything's finished, someone with the right GitHub permissions will merge your changes into PyBaMM main repository.

Recommended issues to work on

A good place to look for documentation issues is #3392, take a look at the list of todo items under the heading "API Docs - Small fixes suitable for first time contributors". If you pick one of these, hover over the item then click the "convert to issue" icon that appears on the right hand side of the item. This will create an issue, which you can navigate to and edit the title and description to make clear what you are proposing to do.

Note that the #3392 issue lists a lot of places to improve the documentation, but it is by no means an exhaustive list. If you see any part of the documentation that could be improved, a docstring missing, or an argument or return type not defined, please feel free to open an issue and implement a fix for this.

Another place to look for more general issues is to filter the list of PyBaMM issues by the "easy" label, like so.

[MehrdadBabazadeh]

Thanks for the great descriptions. Adding a graphical instruction might also be helpful!

[kratman]

@martinjrobins Since the hackathon is over, I am going to close this ticket