-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
MDEV-39456: Describe the external contributions process in more details #5007
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,314 @@ | ||
| # Community Contributions Process # | ||
|
|
||
| MariaDB Server is an Open Source project that thrives thanks to its community. | ||
| MariaDB Foundation handles all community contributions in a timely manner. | ||
|
|
||
| This document provides a description how community contributions are processed. | ||
| Please make sure to familiarize yourself and follow the process | ||
| when submitting contributions. | ||
|
|
||
| All community contribution pull requests will eventually get the | ||
| "External Contribution" label at some point. | ||
|
|
||
| ## The two sides of a contribution | ||
|
|
||
| A contribution should have **BOTH** a design document | ||
| in [Jira](https://jira.mariadb.org) and a pull request | ||
| in [GitHub](https://github.com/MariaDB/server). | ||
|
|
||
| In the normal case the process usually starts with filing | ||
| a [Jira](https://jira.mariadb.org) for the bug or the feature proposed. | ||
| Then a pull request gets created to implement the feature or fix the bug. | ||
| It could be the other way around too. | ||
| But it's important to always have both prior to review. | ||
|
|
||
| There are constant efforts (including background processes) to make sure | ||
| the states of the Jira and the corresponding pull request(s) are kept in sync. | ||
|
|
||
| ### What should go into the jira ### | ||
|
|
||
| The [Jira](https://jira.mariadb.org) is used to describe the design of the | ||
|
gkodinov marked this conversation as resolved.
|
||
| feature: why is it a good idea, what should work, what might not work etc. | ||
| Or to describe the bug: what is wrong, how to recreate it, | ||
| what's the expected outcome etc. | ||
| See [here](https://mariadb.org/contribute/#contribute-to-testing) | ||
| for more details. | ||
|
|
||
| > [!TIP] | ||
| > For faster processing always fill all of the applicable Jira fields: | ||
| > versions affected, component, etc. | ||
|
|
||
| > [!TIP] | ||
| > A lot of time an energy can be saved, especially on more complex tasks, | ||
| > by communicating early with possible reviewers and writing down a design | ||
| > specification into the Jira prior to implementation | ||
|
|
||
| > [!CAUTION] | ||
| > If the jira already exists and is assigned to somebody please reach out | ||
| > to them **before** starting to working on it to avoid effort duplication. | ||
|
|
||
| ### What should go into the pull request ### | ||
|
|
||
| The pull request is used to describe the implementation. | ||
| E.g. how the bug is fixed. Or how the feature is implemented in detail. | ||
|
|
||
| The pull request should contain a **single commit** per logical change! | ||
| And that commit should have a commit message that's compliant with | ||
| the [MariaDB coding standards](https://github.com/MariaDB/server/blob/main/CODING_STANDARDS.md#git-commit-messages). | ||
|
|
||
| > [!IMPORTANT] | ||
| > Put the Jira reference, e.g. "MDEV-12345 ", as a prefix | ||
| > to your pull request's title | ||
|
|
||
| > [!CAUTION] | ||
| > If there's no Jira or no reference to it in your pull request | ||
| > there might be delays in processing it | ||
|
|
||
| ## States of a Community Contribution ## | ||
|
|
||
| ```mermaid | ||
| stateDiagram-v2 | ||
| [*] --> Draft | ||
| Draft --> Closed : 3 Months of inactivity | ||
| Draft --> Open | ||
| Open --> Closed : Rejected | ||
| state "Preliminary Review" as PR | ||
| state "Final Review" as FR | ||
| Open --> PR | ||
| PR --> Draft : 21 Days of inactivity | ||
| PR --> FR | ||
| PR --> Closed : Rejected | ||
| FR --> PR | ||
| FR --> Draft : 21 Days of inactivity | ||
| FR --> Approved | ||
| FR --> Closed : Rejected | ||
| Approved --> Merged | ||
| Merged --> [*] | ||
| Closed --> [*] | ||
| ``` | ||
|
|
||
| ### Draft ### | ||
|
|
||
| * Pull request | ||
| * State: Draft | ||
| * Assignee: Not relevant | ||
| * Label: optionally "need feedback" and/or "External Contribution" | ||
| * Jira | ||
| * State: absent or in "Stalled"/"Open"/"Confirmed" | ||
| * Assignee: Not relevant. | ||
|
|
||
| Contributions in this state are are excluded from any queues. | ||
| Except for the 3 months close period when they need feedback. | ||
| Put your contribution in Draft mode if it's not yet ready for | ||
| preliminary review. | ||
| Or if you want to sketch some sort of a pull request draft | ||
| to *manually* show to people. | ||
|
|
||
| At any time the pull request can be transitioned to "Open" state | ||
| by clicking the "Ready for review" button in | ||
| the GitHub pull request viewer UI. | ||
|
|
||
| > [!NOTE] | ||
| > There is a background process to move contributions in | ||
| > that state to "Closed" state if they have the "need feedback" | ||
| > and "External Contribution" pull request labels and there's | ||
| > been no activity for 3 months. | ||
|
|
||
| ### Open ## | ||
|
|
||
| * Pull request | ||
| * State: Open | ||
| * Assignee: Not relevant | ||
| * Label: not relevant | ||
| * Jira | ||
| * State: "Stalled", "Confirmed" or "Open" | ||
| * Assignee: Not relevant | ||
|
|
||
| Contributions in this state should be ready for review. This means: | ||
| * There should be a single commit per logical change in the pull request | ||
| and this commit must | ||
| * have a commit message that corresponds to the MariaDB Server coding | ||
| standards, including the Jira reference. | ||
| * contain a concise description of what the change is: | ||
| this goes to the git commit log and is used for reference. | ||
| * should contain all the relevant attribution headers | ||
| (co-authors, reviewers etc.) | ||
| * The pull request should contain at least a copy of | ||
| the commit message. Ideally more can be added to it. | ||
| * The pull request should target the | ||
| right branch. | ||
| Rule of thumb: the lowest affected but not older than three years | ||
| GA branch for bugs, main branch for features and refactorings. | ||
| * All the relevant buildbot tests should be passing. Or, if failing, | ||
| the failures should be studied, compared to the test results on the | ||
| target branch (https://buildbot.mariadb.org/#/grid?branch=BRANCHNAME) | ||
| and justified as unrelated. | ||
| * The licensing of the pull request should be clear. As a legal requirement, | ||
| you must accept the CLA (contributor license agreement, also called MCA, | ||
| MariaDB Contributor Agreement) or, alternatively, license your contribution | ||
| under the 3-clause BSD license. See the | ||
| [MariaDB Contributor Agreement FAQ](https://mariadb.com/docs/general-resources/community/community/legal-documents/mariadb-contributor-agreement-faq) | ||
| for the difference between these two options and when to use what. | ||
|
|
||
| Questions and Answers | ||
|
gkodinov marked this conversation as resolved.
|
||
| * When to move a contribution to Open state? | ||
| * When you're ready to submit it to a preliminary review | ||
| * Who moves a contribution to Open state? | ||
| * Usually the submitter | ||
| * What states can the contribution be moved to? | ||
| * Preliminary review, when the preliminary review starts | ||
| * Final review, if the final review starts before the preliminary | ||
| * Closed, if rejected or has the "need feedback" pull request label and | ||
| has been inactive for 3 months | ||
| * Who creates the Jira issue? | ||
| * If there isn't one already, the submitter can and should create it | ||
|
|
||
|
|
||
| > [!NOTE] | ||
| > There is an asynchronous process that assigns "External Contribution" | ||
| > label to pull requests in this state, if absent. | ||
| > This marks the contribution entering the preliminary review queue. | ||
|
|
||
| ### Preliminary Review ### | ||
|
|
||
| * Pull request | ||
| * State: Open | ||
| * Assignee: The preliminary reviewer | ||
| * Label: External Contribution | ||
| * Jira | ||
| * State: "Open", "In Progress", "Stalled" or "Needs feedback" | ||
| * Assignee: The preliminary reviewer | ||
| * Label: "Contribution" | ||
|
gkodinov marked this conversation as resolved.
|
||
|
|
||
| Contributions enter this state usually from "Open" state. | ||
| The preliminary reviewer does the following: | ||
| * Ensures that the contribution is ready for review: has jira, | ||
| tests pass, standards are followed etc. | ||
| * Provides a best effort technical review(s) of the content. | ||
| Note that the preliminary reviewer is not a domain expert, | ||
| so take that review with a grain of salt. | ||
| This is done to save time the final reviewer's time. | ||
|
vuvova marked this conversation as resolved.
|
||
| * Follows up so that their remarks are addressed. | ||
| * Moves the contribution to Draft if the contributor is inactive | ||
| for 3 weeks. | ||
| * Moves the contribution to "Final Review" when done. | ||
| * Assigns a "contribution" label to the Jira and makes sure | ||
| it has "Critical" priority. | ||
| * Can assign a "rework" label to community contribution pull requests. | ||
| This means that reviews are done through some other process. | ||
| Or that an internal developer has taken over the contribution to | ||
| re-do it and push it directly. | ||
|
|
||
| ### Final review ### | ||
|
|
||
| * Pull request | ||
| * State: Open | ||
| * Assignee: The current final reviewer | ||
| * Label: External Contribution | ||
| * Jira | ||
| * State: "In progress", "In review", "In testing", "Stalled", | ||
| "Needs feedback" | ||
| * Assignee: The final reviewer (when actively reviewing) or the | ||
| preliminary reviewer, when waiting for reply by the contributior | ||
| for too long | ||
| * Label: "Contribution" | ||
|
|
||
| Contributions enter this state when the preliminary review is done. | ||
| Or if a certain domain expert takes interest into an incoming contribution | ||
| and starts interacting with it prior to the preliminary review. | ||
| The final reviewer is either a domain expert or a test engineer. | ||
| There can be more than one final reviewers assigned: usually done for | ||
| more complex contributions or when a separate testing step is required. | ||
|
|
||
| Watch the jira state and the assignees in this state for | ||
| detailed information: | ||
| * "In review" means that somebody is assigned to review and they are | ||
| working on it | ||
| * "Stalled" means that they're waiting on something. Also watch | ||
| the assignee in that state. If the jira is re-assigned back | ||
| from a final reviewer to a preliminary reviewer, this means | ||
| that the final reviewer waited for reply by the submitter | ||
| for some time and have (temporarily) moved on by | ||
| moving the Jira to "In progress" and assigning it back to the | ||
| preliminary reviewer. When a reply is received the preliminary | ||
| reviewer will move the jira back to "In review" or "In testing" and | ||
| re-assign to the final reviewer that has requested the feedback. | ||
| * "In testing" means a test engineer is assigned and they are working on | ||
| testing this. | ||
| * "Needs feedback" means that the reviewer needs feedback to proceed | ||
| * "In progress" means that the preliminary reviewer has picked this up | ||
| and is working on it. | ||
|
|
||
| **Try to avoid getting into the re-assignment loop by being active!** | ||
|
|
||
| > [!NOTE] | ||
| > There's a requirement that certain contributions need to undergo | ||
| > a separate test step. This is usually done for the new features or | ||
| > for more complex and risky bug fixes. If that's the desired state, | ||
| > a test engineer will be assigned as a final reviewer. See | ||
| > https://mariadb.com/docs/server/reference/product-development/mariadb-quality-development-rules | ||
| > for more details. | ||
|
|
||
| > [!TIP] | ||
| > The final reviewer is usually a core server developer. They often work | ||
| > in cycles, timed to match the release schedule, switching between | ||
| > bug fixing and new feature development. If a bug fix PR comes | ||
| > in the middle of the new feature development cycle or vice versa | ||
| > it might take up to a couple of months for a developer to do a review. | ||
|
|
||
| ### Approved ### | ||
|
|
||
| * Pull request | ||
| * State: Open | ||
| * Assignee: The last final reviewer | ||
| * Label: External Contribution | ||
| * Jira | ||
| * State: "Approved" | ||
| * Assignee: The last final reviewer | ||
| * Label: "Contribution" | ||
|
|
||
| Contributions in that state are ready to be merged. Usually it's the last | ||
| final reviewer's job to trigger the merge of the pull request and update | ||
| the Jira accordingly. But sometimes the preliminary reviewer can help with | ||
| that too. | ||
|
|
||
| Prior to merging the pull request it should be rebased to the latest in | ||
| the target branch. Thus the contributor should be watching for any | ||
| possible merge conflicts or test failures during that rebase. | ||
| The person that does the merge might need some assistance by the contributor. | ||
|
|
||
| When the pull request is successfully merged the Jira should be moved to | ||
| "Closed" state and its target version should be specified. | ||
|
|
||
| ### Merged ### | ||
|
|
||
| * Pull request | ||
| * State: Merged | ||
| * Assignee: not applicable | ||
| * Label: External Contribution | ||
| * Jira | ||
| * State: "Closed" | ||
| * Assignee: not applicable | ||
| * Label: "Contribution" | ||
|
|
||
| This is the "success" final state for a contribution. | ||
| Ideally all contributions will end up in this state. | ||
| No further actions are necessary. | ||
|
|
||
| ### Closed ### | ||
|
|
||
| * Pull request | ||
| * State: Closed | ||
| * Assignee: not applicable | ||
| * Label: eventually "need feedback" | ||
| * Jira | ||
| * State: "Closed" | ||
| * Assignee: not applicable | ||
|
|
||
| This is the "failure" final state for a contribution. | ||
| A contribution can land in this state for one of the following reasons: | ||
| * It was rejected by the reviewers | ||
| * It was retracted by the contributor | ||
| * It was closed due to contributor's inactivity or lack of replies to | ||
| questions, as signified by the presence of the "need feedback" label | ||
| into the pull request. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.