Overview

GitHub handles contributions as pull requests to relevant repositories part of the Eclipse Oniro for OpenHarmony organization. The flow for handling that is classic: fork-based pull requests. This means that once you have an account, you can fork any repository, create a branch with proposed changes and raise a pull request against the forked repository. More generic information you can find on the GitHub's documentation as part of "Working with forks".

Git setup

Clone your fork locally, enter its directory and set:

$ git config --local user.email <your_eclipse_account_email>
$ git config --local user.name <your_eclipse_full_name>

If you want to push or pull repositories using SSH, you have to add a SSH key to your profile.

Commit Guidelines

💡 NOTE： If you are new to git, start by reading the official Getting Started Document.

At its core, contributing to the project means wrapping your work as git commits. How we handle this has an impact on rebasing, cherry-picking, back-porting, and ultimately exposing consistent documentation through its logs.

To achieve this, we maintain the following commit guidelines:

  • Each commit should be able to stand by itself providing a building block as part of the pull request (PR).
    • A good balance of granularity with scoped commits helps to handle backports (e.g. cherry-picks) and also improves the ability to review smaller chunks of code taking commit by commit.
  • Changes that were added on top of changes introduced in the PR, should be squashed into the initial commit.
    • For example, a PR that introduced a new feature and, as a separate commit, fixed a build error. The latter commit should be squashed into the initial commit.
    • For example, a PR introducing a new docs chapter and also adding, as a separate commit, some typo fixes. The latter commits should be squashed into the initial commit.
    • There is a small set of exceptions to this rule. All these exceptions gravitate around the case where an PR, even if it provides multiple commits in the same scope (for example, to the same new feature), each of the commits has a very specific purpose.
      • For example, a line formating change followed by a chapter addition change in the same documentation file.
      • Also, it can be the case of two functional changes that are building blocks in the same scope.
      • Another example where commits are not to be squashed is when having a commit moving the code and a commit modifying the code in the new location.
  • Make sure you clean your code of trailing white spaces/tabs and that each file ends with a new line.
  • Avoid merge commits as part of your PR. Your commits should be rebased on top of the HEAD of the destination branch.

As mentioned above, git log becomes informally part of the documentation of the product. Maintaining consistency in its format and content improves debugging, auditing, and general code browsing. To achieve this, we also require the following commit message guidelines:

  • The subject line (the first line) needs to have the following format: scope: Title limited to 80 characters.
    • Use the imperative mood in the subject line for the title.
    • The scope prefix (including the colon and the following whitespace) is optional but most of the time highly recommended. For example, fixing an issue for a specific part of the code, would use the part name as the scope.
    • The title (the part after the scope) starts with a capital letter.
    • The entire subject line shouldn't exceed 80 characters (same text wrapping rule for the commit body).
  • The commit body separated by an empty line from the subject line.
    • The commit body is optional but highly recommended. Provide a clear, descriptive text block that accounts for all the changes introduced by a specific commit.
    • The commit body must not contain more than 80 characters per line.
  • The commit message will have the commit message trailers separated by a new line from the body.
    • Each commit requires at least a Signed-off-by trailer line. See more as part of the /contributing/dco{.interpreted-text role=”doc”} document.
    • All trailer lines are to be provided as part of the same text block - no empty lines in between the trailers.

Additional commit message notes:

  • Avoid using special characters anywhere in the commit message.
  • Be succinct but descriptive.
  • Have at least one trailer as part of each commit: Signed-off-by.
  • You can automatically let git add the Signed-off-by by taking advantage of its -s argument.
  • Whenever in doubt, check the existing log on the file (<FILE>) you are about to commit changes, using something similar to: git log <FILE>.

Example of a full git message:

busybox: Add missing dependency on virtual/crypt

Since version 1.29.2, the busybox package requires virtual/crypt. Add this
to DEPENDS to make sure the build dependency is satisfied.

Signed-off-by: Joe Developer <joe.developer@example.com>

Creating pull requests

Once your changes have been pushed to your fork, you are ready to prepare a pull request.

  1. Go to your repository in an internet browser.
  2. Create a pull request by clicking Contribute and press Open pull request. Add an explainable description and create a pull request. Alternatively, you can enter the website of your fork. You should see a message that you pushed your branch to the repository. In the same section you can press Open pull request.
  3. Before merging, it has to be reviewed and approved by repository maintainers. Read their review and add any required changes to your pull request.
  4. After you polish your pull request, the maintainers will run the pipelines which check if your changes do not break the project and approve them. If everything is correct, your work is merged to the main project. Remember that each commit of the pull request should be a minimum, self-contained building block.