Skip to content

Latest commit

 

History

History
96 lines (76 loc) · 5.66 KB

IDEasy-contribution-rules-and-guidelines.adoc

File metadata and controls

96 lines (76 loc) · 5.66 KB
Table of Contents

Project Board

The IDEasy Project Board with its Columns should be used as followed:

  • New: Issues that are newly created and have yet to be refined

  • Backlog: Issues that are refined but not yet being worked on

  • Research: Issues that are blocked or need complex research/analysis to make progress. Typically, these are issues that somebody tried to solve but it turned out to be hard to make progress and find a solution.

  • In Progress: Issues that are currently being worked on, they must be assigned to the person (or people) working on it. You can see on the board if there is a pull-request linked to it. If not, the developer is still working on the story “in the dark”. Otherwise, there is already a solution implemented. The PR may be in draft state, otherwise the PR should be in one of the following two columns.

  • Team Review: Pull Request that is to be or currently under review by a member of the dev team. The reviewer is the assignee of the PR and the author remains assignee (2 assignees).

  • In Review: Pull Request that is to be or currently under review by a final reviewer that is the assignee of the PR together with the author (2 assignees). Typically the final reviewer is the Project Owner (currently hohwille) but it may also be done by team members with longer experience in the project.

  • Done: Issues and Pull Request that have been completed and merged.

To better organize the board and avoid overload, only pull request are allowed in the review columns. Issues remain in progress until completed via merge of PR.

General conventions for contributions to devonfw can be found here. The following conventions are added on top by the IDEasy team from the learnings & retros for our best way of working together:

Pull Request

  • The title starts with a hashtag and the corresponding issue number (in case there is no issue to the PR, either create one or use a fitting epic)

  • The title describes what the PR contains, if an issue is fully completed with the PR, the issue title could be used for example.

  • The description starts with a link to the related issue, if this PR finishes the issue, the following keyword should be used to automatically link and close the issue upon merging the PR:

  • The description can also contain additional information for the PR and changed files.

  • More complicated pull request should contain a short summary of the changed files and commits.

  • In addition, other issue or PRs can be linked, most commonly with keyword like:

    • Blocked by

    • Related

    • Merge first

  • Comments requested changes and other conversations in a pull request should only be resolved by the person that started them and NOT the creator of the pull request. (As the permissions might not always allow this, a final comment by the creator of the conversations, saying it can be resolved is the second 0ption.)

  • Conversations should be answered by the owner of the pull request, so to show that the suggestion was either implemented or acknowledged.

  • The pull request should be assigned to the person that has work on the PR, either the reviewer or the owner depending on whether a review is to be done or the review needs to be addressed.

  • A pull request should not be a draft when it is in a review.

Commit

  • Commit messages should always start with the issue number and a hashtag, so to automatically link the corresponding issue.

  • The title of a commit should be kept short and informative.

  • The description of a commit message can be used to elaborate on the title.

  • Always commit your changes in small logical units associated with an issue (see above section) using the commit message format:

#«issue-id»: «describe your change»

  • Then GitHub will automatically link the commit with the issue.

  • Example:

#1: added REST service for tablemanagement
Implemented REST TableManagement class
Added unit tests for TableManagement class

  • In case you worked on an issue from a different repository (e.g. change in ide-settings due to an issue in IDEasy), we use this commit message format:

«organization»/«repository»#«issue-id»: «describe your change»

  • Example:

devonfw/IDEasy/#5: added REST service for tablemanagement

Issue

  • Issues should be written clearly and easy to comprehend.

  • Issues should use the existing template.

  • The goal or requirements of the issue should be explained first.

  • Potential or desired implementations can or should be described after the preview point.

  • A very good practice and nice to have, are acceptance criteria for the issue.

  • Other issues can be linked using a hashtag and the issue number, most commonly used keywords:

    • Related to

    • Blocked by

Review

  • The reviewer should be assigned to the PR, if a review is needed, or the requested changes need to be checked and conversations need to be resolved.

  • After completing the review, the owner of the PR should be assigned.

  • After the team review is finished the PO (hohwille) should be assigned.

  • While reviewing a useful tool is the web ide provided by github. Simply open the files changed tab and press . on the keyboard.

  • Another useful tool is to use the feature “insert a suggestion” while writing a comment (for more detail see https://haacked.com/archive/2019/06/03/suggested-changes/) (This feature does not reformat the code, so be aware that you need to manually add the spaces etc.)