8

Merge Request Guidelines

Ian McInerney edited this page 2020-07-11 18:55:58 +00:00

Table of Contents

• General Guidelines:
• Code style and formatting
• GitLab settings

KiCad welcomes contributions via merge requests on GitLab. Here are some tips to help make sure your contribution can be accepted quickly:

General Guidelines:

1. Always create a new branch for merge requests instead of using your fork's master branch.
2. Make sure your code submission follows the KiCad Code Style Guide, see below for some details.
3. Make sure all User Interface changes follow the User Interface Guidelines.
4. If you are planning a large change or new feature, be sure to ask on the developer mailing list before you begin your work to see if anyone else is working on it and to ensure that it fits into the overall development plans.
5. Give merge requests a short and descriptive title that summarizes the major changes it contains. A longer description of the changes should be contained inside the description of the merge request.

Code style and formatting

Make sure to read the KiCad Code Style Guide if you haven't already. You can use the clang-format tool to check many, but not all, of these style requirements. When you create a merge request, one of the CI pipeline steps will be to run a formatting check on your contribution. This automatic check is not always 100% correct. Some tips to interpreting the results of automatic format checks:

1. Some of our formatting guidelines have exceptions, or only apply to certain situations. clang-format doesn't know about these nuances, so it will sometimes suggest that you make sweeping format changes to areas of a file near your code (even if you didn't change that code). Keep in mind Rule 7 of the style guide: when there is flexibility or doubt, follow the existing formatting of the file you are editing, rather than rigidly following clang-format.

2. clang-format doesn't know about our desire for nice column-formatting where applicable (Rule 4.1.2)

3. clang-format doesn't support our preferred lambda format (Rule 4.10)

4. clang-format suggests that you alphabetize any #include directives at the top of a file. Please do not do this for existing files unless you are making sweeping changes to the list of #includes anyway.

GitLab settings

Please configure your personal fork of the KiCad project with the following settings:

1. Settings->General->Visibility->Pipelines should be enabled and set to "Everyone with access".
2. Settings->CI/CD->General Pipelines timeout should be set to 3 hours or longer
3. The "Allow commits from members who can merge to the target branch." option check box at the bottom of your merge request must be checked.