我的书签
添加书签
移除书签Contributing to Projects
All bugs and enhancements are tracked in corresponding GitHub issues. If you are unsure where to start, you can pick one of the issues marked with “Help Wanted” or “Good First Issue” labels. For a general usage please ask questions and join discussions in Discord and . If you are reporting a bug, please help to speed up problem diagnosis by providing as much information as possible. Ideally, that would include a small sample project that reproduces the problem.
Helping to review pull requests is another great way to contribute. Your feedback can help to shape the implementation of new features. When reviewing pull requests, however, please refrain from approving or rejecting a PR.
All contributions should target the branch. Project teams will pick the changes to correct version branches from the master.
A quality patch follows good coding practices - it’s easy to read and understand. For more complicated fixes or features, break down the change into several smaller easy to understand patches.
Describe Your Changes
Subject line
Start with a good subject message in imperative form with 50 chars or less. A well formed Git PR subject line should always be able to complete the following sentence: “If applied, this PR will <your subject line here>”
Depending of type of changes you are doing, the subject line should start with feat, , chore or refactor. In case there are breaking changes, put after the prefix, like refactor!:. If you are not sure what to write there, let the reviewer do it when merging the PR.
Show code
Example subject line
Expand code
Describe the problem
Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that motivated you to do this work. Convince the reviewer that there is a problem worth fixing and that it makes sense for them to read past the first paragraph. This is often already described in bug/enhancement issue, but also summarise it in your commit message.
Show code
Example problem explanation
Expand code
Describe the user impact and solution
Once the problem is established, describe what you are actually doing about it in technical detail. It’s important to describe the change in plain english for the reviewer to verify that the code is behaving as you intend it to. Describe your changes in imperative mood, for example “make xyzzy do frotz”. If the patch fixes a logged bug entry, refer to that bug entry by number or URL. However, try to make your explanation understandable without external resources.
If your description starts to get long, that’s a sign that you probably need to split up your patch. See “”.
Show code
Example user impact and solution explanation
Expand code
Reference the issue
Reference an issue number using the magic words to close the issue:
If the issue is not closed by this PR, you can still refer to it with the syntax: Part of #1234. In case the issue is in another repository, you can link to it with the syntax: where the first part is for the organization, the second for the repository followed by the issue (or PR) number there.
Show code
Example issue reference
Expand code
Complete PR message example
Show code
Expand code
Separate all enhancements, fixes, and new features into different pull requests.
For example, if your changes include both bug fixes and performance enhancements, separate those changes into two or more patches. If your changes include an API update, and a new component which uses that new API, separate those into two patches.
If one patch depends on another patch in order for a change to be complete, that is OK. Add note “this patch depends on patch X” to your patch description.
When dividing your change into a series of patches, take special care to ensure that the project builds and runs after each patch in the series. Compilation failures are especially annoying to deal with.
Style-Check Your Changes
Check your patch for basic style violations. There should be none if you have setup your project following the instructions.
If you are touching old files and want to update them to current style conventions, please do so in a separate commit/PR. It is best to have this commit as the first in the series.
Where applicable, patches should be accompanied with . It allows to detect regressions during the build thus simplifying future maintenance. Unit tests are the easiest to implement, but certain aspects (changes to the UI or session management code) might require an integration test.
After submitting a pull request, CI system triggers the verification build automatically, including integration tests, and reports results to the PR.
Test cases should succeed with the patch and fail without the patch. This is a clear indication that the suggested fix/enhancement does what expected.
If the patch is aimed at the performance improvement, supplement it with a performance test code and a benchmark results showing performance impact.
Respond to Review Comments
Code review is an essential part of PR acceptance process and is often a logical continuation of a discussion started in a GitHub issue. Don’t be offended if reviewer asks you to change the implementation or use a different approach. Such changes are often required to align API with a new features being actively developed and to ensure backward-compatibility.
It is best to keep the conversation going in review comments and resolve all reviewer comments. If the PR is not approved by the reviewer and there is no response from the author in a reasonable time, PR is likely to be rejected as abandoned.
Another aspect to keep an eye on is that, as the time goes, more and more new features and fixes are merged into the master branch. As a result, the more PR is waiting to be merged, the higher is the probability of merge conflicts. Such conflicts must be resolved before the merge.
