diff --git a/docs/process/guidelines/contribution_request/_assets/score_contribution_request_simple.drawio.svg b/docs/process/guidelines/contribution_request/_assets/score_contribution_request_simple.drawio.svg new file mode 100644 index 0000000..e6d6eb5 --- /dev/null +++ b/docs/process/guidelines/contribution_request/_assets/score_contribution_request_simple.drawio.svg @@ -0,0 +1,4 @@ + + + +
Contributor
Contributor
Committer
Committer
GitHub
GitHub
Create
PR
Create...
Review
PR
Review...
Merge
PR
Merge...
Actor
Actor
PR
PR
OpenMerged
Contributor
Contributor
Actor
Actor
Actor
Actor
Committer
Committer
GitHub
GitHub
notify
notify
creates
creates
request
review
request...
notify
notify
approve
approve
review
review
notify
notify
add to
merge queue
add to...
pass
pass
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/process/guidelines/contribution_request/_assets/score_contribution_request_standard.drawio.svg b/docs/process/guidelines/contribution_request/_assets/score_contribution_request_standard.drawio.svg new file mode 100644 index 0000000..23c665f --- /dev/null +++ b/docs/process/guidelines/contribution_request/_assets/score_contribution_request_standard.drawio.svg @@ -0,0 +1,4 @@ + + + +
Create PR
Create PR
*
Contributor
Contributor
Committer
Committer
GitHub
GitHub
Request review
Request review
*
Review PR
Review PR
*
Approve PR
Approve PR
*
[met]
[met]
Add PR to merge queue
Add PR to merge queue
*
[not met]
[not met]
Resolve and
commit changes
Resolve and...
*
Re-request review
Re-request review
*
Review and
Acceptance
criteria
met?
Review and...
Check PR
Check PR
*
[not met]
[not met]
[not passed]
[not passed]
[passed]
[passed]
Check
passed?
Check...
[met]
[met]
PR
[Open]
PR...
PR
[Merged]
PR...
Formal aspects met?
Formal aspects met?
PR
[Draft]
PR...
Convert PR
Convert PR
*
Want to
continue?
Want to...
[yes]
[yes]
[no]
[no]
PR
[Closed]
PR...
Close PR
Close PR
*
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/process/guidelines/contribution_request/_assets/score_discussion_request_options.drawio.svg b/docs/process/guidelines/contribution_request/_assets/score_discussion_request_options.drawio.svg new file mode 100644 index 0000000..49de839 --- /dev/null +++ b/docs/process/guidelines/contribution_request/_assets/score_discussion_request_options.drawio.svg @@ -0,0 +1,4 @@ + + + +
ISSUE
[Open]
ISSUE...
PR
[Open]
PR...
creates
creates
creates and links PR
creates and links PR
Contributor
Contributor
PR
[Draft]
PR...
convert to
convert to
ready for review
ready for review
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/process/guidelines/contribution_request/index.rst b/docs/process/guidelines/contribution_request/index.rst new file mode 100644 index 0000000..0d143d4 --- /dev/null +++ b/docs/process/guidelines/contribution_request/index.rst @@ -0,0 +1,131 @@ +.. + # ******************************************************************************* + # Copyright (c) 2024 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +############################### + Contribution Request Guideline +############################### + +Contributions to the *Score* project are the key to grow the content including the code. Contributions may cover simple improvement proposals, bug or problem reports, but also more complex scope changes of features up to new feature requests. Depending on the contribution scope, several steps may be required to finally merge it within the *Score* repository. + +This guidance shall help the contributor (TODO-need`Contributor `) to find the right path for his contribution. + +For simple contributions, like fixing bugs or improvements, just creating a PR is sufficient. + +For more complex contributions, like adding a new feature, where it's unfitting to just open a PR, open an ISSUE to discuss with the community before starting work on it, would be the preferred way. + +You can also join our Slack for real-time discussions. + +The *Score* project defines a Contribution Request (**COR**) as any defined and allowed trigger to start the active contribution to the *Score* project. That means obviously that a PR is a Contribution Request. + +Summary: + +* You want to report something (like a bug) or start a discussion where you do not know the code solution yet, open a GitHub Issue (TODO-need`GD_Issue_Guidance`). +* You want to manage complex coordination problems (planning activities) that require collaboration across multiple stakeholders, open a GitHub Issue (TODO-need`GD_Issue_Guidance`). +* You want to propose a scope change of a feature or a new feature, open a GitHub issue (TODO-need`GD_Issue_Guidance`) and add required PRs to that GitHub Issue. +* You want to report a bug or problem including a code solution? Start with a PR (TODO-need`GD_Pull_Request_Guidance`). +* You want to propose an improvement (also to a process or other work products) including a code solution? Start with a PR (TODO-need`GD_Pull_Request_Guidance`). + +Whenever your PR gets too big or involves committs of several contributors , we strongly encourage to open and link a GitHub Issue, so this can get better planned. + +For a PR to be merged, in any case an approval of a committer is needed. If the committer decides, that only a PR is not sufficient and a GitHub Issue is needed, then the contributor shall also create a corresponding GitHub Issue. + +GitHub Issue are categorized using various types. For categorizing of PRs using of labels, e.g. bug or improvement, is mandatory (ToDO link to the Project Management Plan). + +For all possibilites the project contains simple templates (provided by committers (TODO-need`Committer `)). + +(ToDo link here to the templates overview). +Feature request: TODO-ref`feature_request_template` + +***************************** + What is a Pull Request (PR)? +***************************** + +A Pull Request (**PR**) is the **ONLY** way to contribute **CODE** to the *Score* project. + +The figure below shows a simplified workflow for a PR. + +* The contributor (TODO-need`Contributor `) starts by creating a PR: `Creating a Pull Request (Github Docs) `_. +* Required reviewers will be automatically assigned based on the contributed content (via CODEOWNERS). +* If the content fullfils the review and acceptance criteria, a committer (TODO-need`Committer `) will approve the PR and thus it can be merged. + +.. figure:: _assets/score_contribution_request_simple.drawio.svg + :width: 100% + :align: center + :alt: Simple PR based contribution request workflow overview + + Simple PR based contribution request workflow overview + +Content in general may contain features, requirements, architectural designs, modules, components, detailed designs, implementations and source code, tests, process descriptions, any documentations, guidelines, tutorials, tools, or infrastructure topics and more of the *Score* project. In case of doubt or for any other input we strongly encourage to open a GitHub Issue (TODO-need`GD_Issue_Guidance`) first. + +The PR should provide all required information of the new or changed content. Therefore the *Score* project provides content specific templates, which the contributor (TODO-need`Contributor `) must use for his PR (ToDo link here to the templates overview). Templates may PR templates, GitHub Issue templates and also additional document or work product templates. + +The content of any PR is the commit content and the description as well as the comments given in GitHub and is kept in a versioned repository, their revision history is the historical record of the PR. + +This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed on GitHub. + +************************************** +Detailed *Score* Pull Request Workflow +************************************** + +This chapter is only for optional read to understand the details for the Pull Request workflow defined in *Score*. + +The figure below gives an overview about all the possible steps for a PR until it is either accepted or rejected. + +.. figure:: _assets/score_contribution_request_standard.drawio.svg + :width: 100% + :align: center + :alt: Detailed *Score* Pull request workflow overview + + Detailed *Score* Pull request workflow overview + +Create a PR +=========== + +The contributor (TODO-need`Contributor `) creates a PR. + +Reviewers will be automatically assigned (TODO-need`Committer `) based on the contributed content (ruleset as defined by the committers). In addition several checks for the contributed content (ToDo: Link to the description of the checks) will be started. + +Review and merge a PR +===================== + +A PR is reviewed with all content that adds/modifies it. As long as a PR requires further work by the contributor (TODO-need`Contributor `), the PR is not approved and thus not merged and further changes are requested. Once the contributor (TODO-need`Contributor `) considers all review comments as resolved, TODO-need`Contributor ` can re-request a review. The committer (TODO-need`Committer `) reviews the PR content according the *Score* review and acceptance criteria (ToDo link here to the criteria). +Further the contributor (TODO-need`Contributor `) must resolve found issues from the automated checks, if they do not pass. + +As long as the PR does not meet the defined criteria and the checks does not pass, it will not be approved. If it does not follow the required templates, based on the provided content or the templates are not filled out properly, the committer as reviewer (TODO-need`Committer `) will place the PR to the "Draft" state. + +It is then the responsibility of the contributor (TODO-need`Contributor `) to add the missing information and to re-start the contribution by placing the PR back for review. + +To change from "Draft" to "Open" see `Changing the stage of a pull request (Github Docs) `_. + +At any point the contributor (TODO-need`Contributor `) may decide not to continue with the PR, then the contributor (TODO-need`Contributor `) just closes the PR. + +What is a GitHub Issue? +======================= + +A GitHub Issue is the way to report bugs or propose improvements without knowing the solution and to request features (incl. scope changes). + +For creating GitHub Issue compare here: `Creating a GitHub Issue (Github Docs) `_. + +Create an GitHub Issue to collect feedback, before investing too much effort into a PR. GitHub Issues may be accompanied by draft PRs if code is to be shown. + +It can also be used to collect community input and for planning and tracking activities. + +The figure below shows options to report something. + +.. figure:: _assets/score_discussion_request_options.drawio.svg + :width: 100% + :align: center + :alt: Reporting options overview + + Reporting options overview diff --git a/docs/process/guidelines/index.rst b/docs/process/guidelines/index.rst index 77ff44c..1ff3447 100644 --- a/docs/process/guidelines/index.rst +++ b/docs/process/guidelines/index.rst @@ -12,11 +12,11 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -.. _Configuration_Tool_Guidelines: +.. _Guidelines: -############################# -Configuration/Tool Guidelines -############################# +########### + Guidelines +########### .. toctree:: :maxdepth: 1 @@ -24,4 +24,5 @@ Configuration/Tool Guidelines git/index.rst branch/index.rst - general/index.rst \ No newline at end of file + general/index.rst + contribution_request/index.rst \ No newline at end of file diff --git a/docs/process/index.rst b/docs/process/index.rst index a92958c..462918c 100644 --- a/docs/process/index.rst +++ b/docs/process/index.rst @@ -19,29 +19,26 @@ Process Processes are the basis to describe the way of working within the SCORE project. -Requirements engineering ------------------------- -A key process is the Requirements engineering, which is for defining, documenting, and maintaining requirements within our SCORE project. +Guidelines +---------- -Requirements templates -~~~~~~~~~~~~~~~~~~~~~~ +The guidelines for the SCORE project can be found here: .. toctree:: :maxdepth: 1 :glob: - templates/index.rst - -Configuration/Tool management ------------------------------ + guidelines/index.rst -Important from the begin are version control topics, like commit rules and naming conventions for branches. +Requirements engineering +------------------------ +A key process is the Requirements engineering, which is for defining, documenting, and maintaining requirements within our SCORE project. -Configuration/Tool guidelines -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Requirements templates +~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 1 :glob: - guidelines/index.rst + templates/index.rst