Submitting a pull request
Like many open source projects, MariaDB accepts contributions through pull requests on GitHub, so if you’d like to contribute, you must first create an account on GitHub. After you’ve created the account you can follow these steps:
Fork the project on GitHub
- Go to https://github.com/MariaDB/server
- In the right corner of the screen, click on fork.
Clone the project locally
- First you need to get the code on your machine.
git clone https://github.com/YOUR-USERNAME/server
- It is good practice to check whether there are any untracked files with the git clean dry run option.
git clean -dn
Or you can use
git clean -ito interactively specify what to delete.
- If there are any untracked or ignored files and you are sure that they can be deleted and if you have built MariaDB in the past and have recently updated the repository, you should perform a complete cleanup of old artifacts (such as cmake configured files) from base repository use:
git clean -dffx && git submodule foreach --recursive git clean -dffx
- Go to your local repository directory and create a development branch for your fix and check it out.
git branch fix-bug-server 10.3 git checkout fix-bug-server
Write your patch
- You may want to read up on compiling and testing the server.
- Code your patch and make sure to test it.
- Follow the guidelines for creating a test case and run the full test suite to make sure nothing is broken.
- Commit the patch, including the test and result files. You should usually to submit the patch against the earliest affected version (if a bug) or the latest development version (if a new feature), but ask if unsure.
- Follow the guidelines for writing a good commit message.
- Push the changes to your repository.
When pushing a branch to the remote for the first time, git may complain about having no upstream branch. Just run the command that is suggested there, for example:
git push --set-upstream origin fix-bug-server
- Once the branch is in your repository on GitHub, you will get the benefit of your changes being tested using Travis on multiple configurations. It’s worth it to check results to see if there are any failures. See if any failures are possibly caused by your patch.
Go to GitHub to initiate the pull request
- Open your repository page
- Go to the Pull requests tab and click on New Pull Request.
- Choose the MariaDB repository and main development branch on the base fork side.
- Choose your branch on the other side.
- Make sure the commits you want are in the list, then click on Create pull request.
- Mention in the pull request comment under which license you are providing the code. See pull request licensing below for more details.
We guarantee that every pull request will get a reply. Reviews can take longer, based on the complexity of the patch or the workload of developers. Members from the community may chip in to provide comments, however it is the main reviewer who will have the final say if a patch is accepted or if it requires further improvement.
Pull request licensing
All code in MariaDB comes from one of the following sources:
- Code developed by people employed by the MariaDB Foundation.
- Code developed by people employed by MariaDB Corporation.
- Code shared with the MariaDB Foundation under the MCA.
- Code with a known origin that is under a permissive license (BSD or public domain).
If you want to submit code to the MariaDB Foundation, you must provide a shared copyright to your work. To do this, MariaDB Foundation requires pull requests to be submitted either under BSD New 3 Clause License, or under the MariaDB Contributor Agreement. This enables us to be able to give back contributions to other projects such as MySQL and it would not be possible to do so otherwise.
Best practices for pull requests
Keep your fork in sync
- Before submitting a pull request, it is necessary to make sure your fork is up to date. To sync with upstream, you need to track the upstream repository and rebase on top of it.
git remote add upstream https://github.com/MariaDB/server.git
- Whenever you want to merge with upstream, first fetch any changes with removing any remote-tracking references that no longer exist on the remote, then rebase. This works assuming you never do any work on 10.3 yourself.
git fetch -p upstream git checkout 10.3 && git rebase upstream/10.3
- After rebasing on upstream, it’s useful to push the changes to your github repository.
git push origin 10.3
- If you need to switch to a different branch, for example
10.1, you will need to create a local branch
10.1that is derived from
upstream/10.1and to switch to the newly created branch.
git branch 10.1 upstream/10.1 git checkout 10.1
You can do the same as the above in one line:
git checkout -b 10.1 upstream/10.1
Rebase the bug-fix branch before submitting
- After rebasing the main branch on upstream, you can rebase your bug-fix too.
git checkout fix-bug-server && git rebase 10.3
- Rebasing allows a linear history and prevents unnecessary merge commits. We prefer to avoid merge commits if possible and this is usually the case for bug fixes.
- When updating your pull request (if you got requests from reviewers for changes), do not create a new pull request. Instead, locally, you can work on your bugfix branch to implement the suggestions, create new commits for those, and at the end you can rebase your work interactively by squashing N-1 commits into the one that was originally added to the pull request (which should be picked).
git rebase -i HEAD~N
When you finish with your changes locally, push it to your GitHub repository with
--forceoption. With this step you will also update your pull request.
git push --force origin fix-bug-server
Make sure your commit messages and content follow the following guidelines
- Start the title line with a capital letter.
- A title should be around 70-ish characters, without an ending “.” (full stop).
- Use the imperative format (not “Cleaned” but “Clean up”).
- Leave one empty line after the title.
- Explain what the commit fixes and why. The “how” part is covered in code. Go into implementation details only if the problem needs further context, although these details should be visible in code comments as well. Use your best judgment here.
- Try to keep the same coding style as you see in the files you change.