Development organization - OpenSlides/OpenSlides GitHub Wiki

The project management board: https://github.com/orgs/OpenSlides/projects/2

Before anyone develops on OS4, they have to set the correct remote repos. Our convention is to fork the OpenSlides repo (and the sub-repos to which a developer wants to contribute). Then, the developer set their own (forked) repo as "origin" and the OpenSlides' one as "upstream". This can also be done with the main repo's make command submodules-origin-to-upstream (https://github.com/OpenSlides/OpenSlides/blob/5b6cdb21854b8301412c3d7051e126d4976061ea/Makefile#L43). Afterwards, the workflow is the following:

1. Checkout a new branch with a custom name that is as descriptive as possible
2. Start developing
3. Changes have to be pushed to the remote "origin" branch (by git push -u origin <branch>)
4. Then, create a pull request (PR) to the OpenSlides corresponding repository

All branches in the repositories should be named in kebab-case. They are prefixed by their category, e.g. feature or stable. The category and the branch name are separated with a /.

Feature branches are used for larger features which do not fit comfortably in one PR, and/or are separated into multiple work packages, and/or are very long-running. They must be named identically in each repository which needs it.

In the Backlog column all new issues are inserted that do not require a fix/implementation in the near future. If an issue is urgent (blocker/high), it can be added directly to To Do with the correct labels set.

In Todo are tasks that are focused and must be done before falling back to the backlog. If an issue has the high or blocker label, it is prioritized.

Assign an issue to yourself if you are going to work on this. If you do not find an issue in Todo, you can look in the backlog and move the issue into Todo.

In our regular meeting we will put new issues into the Todo column and prioritize them with the high label.

When creating issues or pull requests in OS4 repositories, all important metadata should be filled out. Here is a full overview on what should be set and when this should be changed:

• Assignees: It should be empy until someone takes the issue to work on it and then assigns himself. Afterwards, additional people should be assigned if input from them is required and de-assigned again when their work is done. One can de-assign him- or herself from an issue if needed, this should be communicated with the team.
• Labels: Use bug or feature if it is one of these kinds. If non of {bug, feature} is assigned, the meaning is a general enhancement, but we do not set extra labels for this. Set additional labels as needed. If in doubt, consult with the rest of the team, e.g. for priorization of issues (see below for more details).
• Projects: This is set automatically by the GitHub action.
• Milestone: Normally, user the most current milestone. If the issue should not be fixed in the near future, consider manually changing it to a later one after creation.

• Reviewers: assign someone (or multiple people) who should review your PR (if in doubt, consult the list of ownerships in the OS wiki: https://openslides-intern.intevation.de/Entwicklung/Services). If it is not ready yet, leave empty until someone should review it.
• Assignees: Assign the persons whose actions are required for this PR to proceed. If you still need to do work, assign yourself; if someone should review it or otherwise fiven their input, assign them. Multiple assignment is allowed and encouraged, if needed.
• Labels: Copy the labels from the issue. If this is waiting for another issue to be fixed first or another PR to be merged first, add the waiting label. Backend only: If this PR introduces a new migration, add the migration label.
• Projects: This is set automatically by the GitHub action.
• Milestone: Copy the milestone from the issue.
• Linked Issues: Link the issue(s) that this pull requests resolves. Also possible by using keywords: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword. Generally, a pull request should have a corresponding issue.

Write your commit messages like they could appear in a change log. The same goes for pull request titles, since these are inserted as the default commit message when merging. The following guidelines are adapted from https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53.

• Keep the subject line short and concise - there is no hard limit on the characters, but max. ~100 characters should suffice. Put additional info in the body, if necessary (see below).
• Capitalize the subject line.
• Do not end the subject line with a period.
• Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. A properly formed git commit subject line should always be able to complete the following sentence:
  • If applied, this commit will <your subject line here>.
• Do not include links or references to issues in the commit message unless specifically needed, since GitHub automatically inserts a link to the PR which in turn is linked to the issue(s) it fixes.
• Specifically for PRs: Do not include "WIP" in the title for draft PRs, but instead use the GitHub draft feature.

If you want/need to provide additional information for a commit (especially when merging a PR), adhere to the following additional rules:

• Separate subject from body with a blank line (automatically done when merging via GitHub).
• Wrap the body at 100 characters.
• Use the body to explain what and why you have done something. In most cases, you can leave out details about how a change has been made. E.g.: "Implemented a cache to reduce network requests", leaving out the fact that you inherited from some class X to do that and unified two helper methods while doing it.
• You may use bullet points where applicable

When merging a PR via GitHub, go through the existing commit messages which are inserted into the body by default and filter out any irrelevant information (e.g. messages like "cleanup"). Also remove the "Co-authored by" entry at the end if not explicitely needed/wanted (e.g. if the feature was developed activelsy by multiple people).

We use the assignment only to indicate, who is currently working on an issue or who is required to do some action.

The required case is meant to be in combination with a needs * label. For example, if there is an issue where discussion or info is needed, the person who can resolve it can be assigned.

As a result only issues in the Backlog can have an assignee if some action is needed. It is not possible to have an assignee in the Backlog, if he/she is working on it (it must be in Todo). This enables searching for issues one could do since only issues in Todo are assigned, someone is working on or action is required. Unassigned issues can be taken for work. Additionally, one has a good overview who is working on which issue.

Assign yourself to the issue and when creating a PR for this issue link the PR to the issue. The PR is automatically added to the project and it will automatically be put into the Work in progress column. The issue remains in To Do. Note that the issue has a 1 linked pull request entry. There is no need to move both the issue and PR through review steps.

If your work is done, move the PR into Review in progress and assign someone to review your changes. The reviewer either accepts and moves it to Reviewer approved, so you can merge it. If the changes were not approved, the reviewer moves it back to Work in progress.

Issues are not allowed to be in one of these three columns. This allows for the usage of the GitHub automation on pull requests.

It is highly encouraged to do pull request reviews, especially for non-small fixes or non-hotfixes! Currently we decided against a required review, but this might be a step to take if there are issues due to merged features without reviews.

After the PR is merged, it and the issue will automatically be moved to Done and the issue will be closed. Note: If there is still something to do in the issue, it must be reopened and moved back to To Do manually.

• needs *: This issue is incomplete and needs some information. This usually requires to be assigned to the person that can resolve the question or provide the needed information.

• blocker: This blocks someone's work and is prioritized higher than critical. If such an issue appears, it has to be resolved first.
• critical: Issues labelled by critical have an critical impact to OpenSlides, if they persist. Therefore, such issues have to be resolved even if one works on other issues with a lower priority.
• high: Issues labelled by high have to be prioritized.
• None (medium): This is the standard priority. There is no label called medium, because every issue without a priority-label (like high or low) is medium. Such issues have to be resolved if there are only issues with the priority low or medium.
• low: Issues labelled by low have the lowest priority. Such issues have to be resolved if there are no issues with other priority labels left.

In addition to the priority labels, issues and pull requests are also assigned to milestones. At the time of writing, issues in milestone 4.1 are the most urgent and important features and bugfixes. Issues in this Milestone should always be worked on first. Milestone 4.x is for less urgent issues which may be done later in the future or enhancements that are not necessary yet. Naturally, issues with priority high or higher should not be put into this milestone.