Contribution Guidelines for Developers en

Gary Wang edited this page Dec 29, 2018 · 10 revisions

Contribution Guidelines for Developers

TODO: Need rewrite. Some of our projects are moving to GitHub from Gerrit, you can directly submit Pull Request from GitHub for the projects which already moved to GitHub. See the appendix for a list of project you can submit PR from GitHub.

We’d like to invite you to contribute changes and make Deepin even better than it is today! Here are the guidelines we’d like you to follow.

Code of covenant

All Deepin projects adheres to the Contributor Covenant 1.2. By participating, you are expected to uphold this code. Please report unacceptable behavior to support@linuxdeepin.com.

Getting code

We host all the code in Gerrit, and synchronize them to GitHub as mirrors in real-time. So you could clone projects from any one of them. But as the unique code-review system, we prefer to accept the pull requests in Gerrit instead of the mirrors. More information about pull-request please have a look at the following tutorial.

Setup for Gerrit

TODO: These steps may be outdated and should be update. You no longer need to import your GitHub account info manually, but you should set at least one public email address in your GitHub account instead. Gerrit will fetch and use your GitHub public email address directly.

  1. Sign in Gerrit through GitHub account.
  2. Access this page to import account information manually. Just press Next and will operate successful result with an empty page. You could repeat the operation later to keep same with the last GitHub account information.
  3. Install git-review command, for example under Debian
    sudo apt-get install git-review
        
  4. Write ~/.config/git-review/git-review.conf with following content to make git-review works well for the projects that missing default configuration
    [gerrit]
    defaultremote = origin
        

    ps: you can use *git review -r origin” to specify the review remote for temporary using.

Submitting a pull request

Clone target project

Please clone project with SSH protocol and commit-msg hook support from Gerrit, you could get the full command in the project description page, here is an example

git clone ssh://<user>@cr.deepin.io:29418/deepin-music && \
  scp -p -P 29418 <user>@cr.deepin.io:hooks/commit-msg deepin-music/.git/hooks/

Checkout new branch

Checkout a new local branch from the correct upstream branch, and keep the name prefix with contrib/ to make the usage clear, for example contrib/network/bug/conn-missed, contrib/display/dev/support-multi-monitors.

Coding style

Before the hacking work, it is strongly recommended to read the code specifications to ensure the uniform style. You could read the specifications for C/C++, Golang and Python in wiki pages(TODO: in process). And for some special projects, reading the HACKING file in root directory will get more useful information.

Beside, an easy way to avoid coding style issue is to run the code analysis tools like pylint and golint. Usually, run make check in source directory will do such work(TODO: in process).

Write your code

Then, the most important part, writing your code.

Besides, please complete the test suite if possible. And run the whole test suite of the affected component. If all tests are passing, that’s enough to propose your contribution.

Commit message

The git commit message also should follow some rules, such as limit the subject line to 50 characters and wrap the body at 72 characters, more detail to see here.

Besides, please append related URLs in separate lines, for example append the Bugzilla URL if it is a bugfix commit.

Code review

Now, it’s time to push the code to Gerrit and waiting for review. Be careful, you must select the correct upstream branch, like this

git review release/1.0

If success, the command will print a new Gerrit review page, please access it and add reviewers. Generally, you should add project owner(s) as reviewer(s). If not sure, just append our community maintainer(@derekdai or @fasheng) as reviewer,

Merge changes

After the code has been reviewed, an approver may submit it to the master branch using the Gerrit UI. There is a “Submit” button on the web page for the change that appears once the change is approved (marked +2).

And we will append the author’s name to CONTRIBUTORS file in the same project later.

Rules

  1. Rules about CHANGELOG
    1. There MUST be a CHANGELOG file under the root directory of project(checked via git ls-tree HEAD | grep -i changelog |head -n1). It is recommended to use the name CHANGELOG.md.
    2. When doing git push --tags, the corresponding tag must exists in the changelog file (checked via grep -F -w $tag $changelog_file)

Appendix: List of projects we already moved from Gerrit to GitHub:

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.