Skip to main content
Code Contribution Guide
Learn the code conventions, contribution workflow, how to review code, and the contributor checklist.

Code of Conduct

Everyone who participates in Apache Cloudberry, either as a user or a contributor, is obliged to follow our community Code of Conduct.

Ready to contribute

Before starting to contribute, please read the guide "How to Contribute" and make sure to learn Git & GitHub well.

Especially as a new code contributor, don't rush to start. We suggest that you understand our project, read the documentation, learn the code conventions, know how to write proposals, and familiarize yourself with the community. Then start small.

You can look for easy issues to fix or small features to add, such as the GitHub Issues with labels “good first issue” and "help wanted" which can help you familiarize yourself with the contribution workflow, and for the dev teams to become acquainted with you.

warning

Don't import components under GPLv2/3 License or other non-OSI licenses for your code, which will interfere with Cloudberry's Apache License. If you are not sure, please contact dev@cloudberry.apache.org.

To avoid duplicating work, please review the Apache Cloudberry Proposals or ask directly in our Slack before you start work on a non-trivial feature.

Code Conventions

Source code should follow the PostgreSQL coding conventions.

Source Formatting

This includes source formatting with 4 column tab spacing, layout rules according to the BSD style and line length within 80 columns. Though there are many different styles in the PostgreSQL codebase we can try to make your patch consistent with nearby code(See discussions in PostgreSQL mailing list.)

We can use existing configurations for Apache Cloudberry development, such as Vim, Emacs, Clion and other editors.

Error Messages

Error messages style follows PostgreSQL Error Message Style Guide.

Contribution workflow

The following will describe how to submit your code contribution as Pull Request to Apache Cloudberry. If you still don't know well how to work with Git and GitHub, please read our guide again.

To contribute to Apache Cloudberry development:

  1. Fork the Apache Cloudberry repo to your own GitHub account.

  2. Clone down the repo to your local system.

    $ git clone https://github.com/your-user-name/cloudberry.git
  3. Add the upstream repo. (You only have to do this once, not every time.)

    $ git remote add upstream https://github.com/apache/cloudberry.git

    now, when you run git remote -v will show two remote repositories named:

    • upstream, which refers to the 'apache/cloudberry' repository
    • origin, which refers to your personal fork
  4. Create a new branch to hold your work.

    $ git checkout -b new-branch-name
  5. Work on your new code. Write and run tests.

  6. Commit your changes. For writing a good commit message, please refer to Commit Conventions.

    $ git add
    $ git commit
  7. Push your changes to your GitHub repo.

    git push origin branch-name
  8. Open a PR(Pull Request).

    Go to the Apache Cloudberry repo on GitHub. There will be a message about your recently pushed branch, asking if you would like to open a pull request. Follow the prompts, compare across repositories, and submit the PR.

    For code contributors, don’t rebase your branch orotherwise modify published commits during the code review process, since this can remove existing comment history and confuse the reviewers when reviewing. When you make a revision, always push it in a new commit.

  9. Get your code reviewed.

    Apache Cloudberry maintainers and other contributors will review your PR. Please participate in the conversation, and try to make any requested changes. If you get no review comments within two weeks, feel free to ask for feedback by ask the cloudberry committers in your PR comment.

    Once the maintainers are happy with your change, they'll approve the pull request. At this point, the maintainer will take over, possibly make some additional touch ups, and merge your changes into the codebase.

  10. Congratulations! Once your PR is approved by at least 2 maintainers with write access, and passes the CI/CD without errors, then the code will be merged. Your code will be shipped in the recent future releases.

note

Before working on your next contribution, make sure your local repository is up to date:

  1. Switch to the local main branch.

    $ git checkout main
  2. Fetch the latest changes from upstream.

    $ git fetch upstream
  3. Rebase your codebase to the upstream main branch.

    $ git rebase upstream/main
  4. Create a new branch if you are starting new work.

    $ git checkout -b branch-name

If you want to update your existing branch with changes from upstream, you need to run git checkout branch-name, then rebase your branch on upstream main by git rebase upstream/main.

We also want your PR to have a clean commit history, but in the real world, you may have pushed multiple commits into a single pull request. To ensure a clean merge, please run git rebase -i to squash your commits down to 1 commit before the pull request is merged.

Learn more:

Code review

We encourage anyone to start reviewing code submitted by other developers, especially if the feature is something that you are likely to use.

Here are some questions to keep in mind during the code review process:

  • Do we want this in Apache Cloudberry? Is it likely to be used? Do you, as a Apache Cloudberry user, like the change and intend to use it? Is this change in the scope of Apache Cloudberry? Will the cost of maintaining a new feature be worth its benefits?
  • Is it too large to review? Does it need to split into multi PR?
  • If it's a proposal, does it have been accepted and start to code?
  • Is it duplicated with other existing code contributions in Cloudberry or commits in upstream projects?
  • Does it follow our code conventions?
  • Does it need to have a proposal before getting the code review?
  • Does the PR have a good commit message following our commit conventions?
  • Does the PR need to rebase to have a clean commit history and be in sync with the base branch?
  • Is the code backward compatible with previous versions?
  • Does its test pipeline run well?
  • Is the code efficient? Could it be rewritten easily to run more efficiently?
  • Will the new code add new dependencies on other libraries?
  • Does the change import new components with licenses incompatible with Apache License V2.0?
  • Does it modify the files' license headers? If so, is it ok?
  • Is the code human-readable? Is it low on redundancy? Should variable names be improved for clarity or consistency? Should comments be added? Should any comments be removed as unhelpful or extraneous?
note

For acronyms and abbreviations used in the code review, you can read here.

Contributor checklist

  • Read the contributing guidelines.
  • Read the Code of Conduct.
  • Check if your changes are consistent with the Apache Cloudberry coding style.
  • Make sure your Pull Request has a clear title and commit message.
  • List your communication in the GitHub Issues or Discussions (if has or needed).
  • Run the unit tests and regression tests.
  • Pass make installcheck, make -C src/test installcheck-cbdb-parallel
  • Import some components with Apache License V2 compatible license.