Contribution Workflow - DLR-AMR/t8code GitHub Wiki

We use a GitHub project board to track contributions with Issues. This means every Pull Request must be linked to an Issue, which will be automatically closed when the PR is merged. Having a look at t8code's Issue Landing page, you will find the state of all issues concerning t8code. If you have a good solution for an issue that has the state "ToDo" / is in the "ToDo"-column, feel free to assign yourself and work on it. It is highly appreciated. In the future we will have specialized Project-boards, where issues to a certain topic are summarized. But at first, all issues will occur on t8code's Issue Landing page.

We tried to minimize the additional overhead for you as much as possible. Nearly all of the steps that an issue will do on the project board are automated. An issue should have the following life-cycle:

1. Opening an issue: It will automatically added to the project and have the status "In-Box".
2. Labeling an issue: If you already know the priority and the workload of the issue, you can give it a label according to its weight. Otherwise we will do it. The issue will be moved to the "ToDo"-column by the t8ddy-bot. Soon we will provide labels to sort issues into different topics. The issue will then also occur on the specialized issue boards.
3. Assigning: You want to work on an issue? You can assign yourself on it, the issue will get the status "In Progress". That way we want to prevent that multiple people are simultaneously working on a solution.
4. Opening a PR: You implemented a solution for the issue on a branch and now you want to merge it into main. Reference the issue by "Closes #ISSUE_NUMBER". The issue gets the status "Needs Review" and we will request a review from somebody of the main-developer Team.
5. Review is requested: You are almost done. Somebody is doing the review for your pull request. The linked issue will get the status "In Review".
6. Merged into main: You are done, and the issue will be moved into "Done". We will talk about the solution shortly in our developer-meeting. Then the issue will be moved into "Can be archived". After two weeks the issue is archived automatically.

Please execute the steps in this order to ensure that your issue has the correct status.

No! If your code is only a couple of lines long AND has very little impact on the algorithms of t8code (a single line of changed code can have a big impact) we encourage you to directly open a PR. If no issues are referenced using the Closes-keyword, an issue is automatically created and moved into "Needs Review". That way we shouldn't miss the opening of your PR.

We welcome all contributions to our library. For a successful contribution to t8code we ask you to open up a draft pull request (Draft PR) into https://github.com/DLR-AMR/t8code/ as soon as you start implementing. If you already have a suitable reviewer in mind, integrate them into the development process as early as possible. That way we can give you tips and discuss your implementation while you are working on it and hopefully avoid big changes in your code after a lot of work has already been done.

Typically, the workload of the review process grows disproportionately with the size of the PR. To avoid big PRs, it is good practice to separate your work into multiple smaller PRs. For example, you can post a first PR for new interface/function declarations and a second PR for implementations (which you may again split into smaller PRs).

Use the label "Follow-up PR" to mark it as a piece of your contribution. Use the same name of your branches and an increasing number to show that the PRs are related (for example: "my_new_feature [2/n]" for the second PR of n for a new feature).

As soon as one of the development team has been assigned responsible for your PR the review process starts. Some improvements will be suggested by our indentation, spell-checking and macro-check workflow, some by us and maybe we want to further discuss a detail of your contribution.

After the first remarks have been made you will be assigned again to the PR and you can respond to all comments and suggestions. When you are done please remove yourself as an assignee and assign the reviewer again, so that they will be notified again.

We hope to ensure an efficient review process that way.

Contributors are required to put their contributions under the FreeBSD license. To do so, add a file doc/author_NAME.txt with the content "I place my contributions to t8code under the FreeBSD license. FIRSTNAME LASTNAME <EMAIL>"