From 6f1be945d3e0cfaa73eb7e73e31da5e198e45d4a Mon Sep 17 00:00:00 2001 From: moritzLanger <44358321+moritzLanger@users.noreply.github.com> Date: Thu, 4 Jan 2024 17:45:37 +0100 Subject: [PATCH] #5: added contributen rules and guideines (#156) --- ...contribution-rules-and-guidelines.asciidoc | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 documentation/IDEasy-contribution-rules-and-guidelines.asciidoc diff --git a/documentation/IDEasy-contribution-rules-and-guidelines.asciidoc b/documentation/IDEasy-contribution-rules-and-guidelines.asciidoc new file mode 100644 index 000000000..0e5d26b24 --- /dev/null +++ b/documentation/IDEasy-contribution-rules-and-guidelines.asciidoc @@ -0,0 +1,110 @@ +:toc: macro +toc::[] + +== Project Board +The IDEasy *Project Board* with its Columns should be used as followed: + +* *New*: [.underline]#Issues# that are newly created and have yet to be +refined +* *Backlog*: [.underline]#Issues# that are refined but not yet being +worked on +* *Research*: [.underline]#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*: [.underline]#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*: [.underline]#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. +* *In Review*: [.underline]#Pull Request# that is to be or currently +under review by a final reviewer that should also be the assignee of the +PR. 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*: [.underline]#Issues# and [.underline]#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 +https://github.com/devonfw/.github/blob/master/CONTRIBUTING.asciidoc#code-changes[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: +** Closes +** For more info see +(https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) +* 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. + +== 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.)