Workflow

This section will cover the workflow in our project.

Git and Gitlab

Git is a version control system for tracking changes in the source code of software projects during development. Gitlab is a web application for version control based on git. Among other things, it provides an issue tracking system, a CI pipeline system, and a wiki.

For an introduction to how we use git for version control, check out Git Introduction.

Working on Issues

  • When an issue is assigned to you, create a related branch:

    • Open the issue in gitlab, click on the little arrow next to “create merge request” and select “create branch”.

  • When committing to this branch, please follow our commit conventions.

  • When you think you have finished your work, and your branch is ready to be merged into develop, create a merge request. We have the following review process:

    • Create the merge request as a draft (The name must start with “Draft: “).

    • Appoint a reviewer who you think fits.

    • The reviewer can now suggest changes. Once they are happy, they “approve” the MR, mark it as ready (remove draft status) and assign it to a maintaner, i.e. Jan.

    • The maintainer will then do a final review, possibly merge your branch into develop, and update the CHANGELOG.md.

Note that if you only implement a really small change, it might be sufficient to only create a merge request and detail your changes there. An example of this could be the following: You are working on an issue but then realize that you first need to implement some other change (sort of like a hot fix). Instead of doing all that in one branch, it is much cleaner to create a separate branch (and merge request). Usually these changes are small and don’t require you to create an issue associated with them.

Testing & Writing Tests

Every time a new feature is added to the library, it is important to write a test. The test has the function to check the correctness of the new feature, as well as ensuring the up-to-dateness of the feature in future versions of the library.

  • See Testing on how to run and write tests

  • Whenever you push your branch to the server, the tests are executed (in the gitlab CI pipeline)

    • If the pipeline fails you will be notified by e-mail

Writing Documentation

Pyddg online documentation:

Documentation is an integral part of developing. The Pyddg Documentation (aka “our docs”) consists of the Users Guide, the Developers Guide and the API Docs. In the users guide, the most important features of pyddg are explained in detail by means of pictures, examples and other additional information. The developers guide contains information for developers on how to contribute to the library. The API docs consist of all functions, classes and their docstrings.