COMMUNITY_CONTRIBUTIONS.md

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 and a pull request in GitHub.

In the normal case the process usually starts with filing a Jira 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 is used to describe the design of the 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 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.

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

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 --> [*]

Loading

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 for the difference between these two options and when to use what.

Questions and Answers

• 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"

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.
• 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.