Apache Cloudberry (Incubating) is hosted on GitHub. We use GitHub Issues as the bug report system, and use Git as our version control system. Given these, it's important for community users and developers to learn how to work well with GitHub and Git.

Please note, we do not aim to write one complete guide for Git or GitHub on this page, but we list the key points in your future work.

Get ready for working​

Step 1: Set up your GitHub.com account​

Before we start, it's necessary to have a GitHub account. If not, please create one.

Then you need to edit your public GitHub profile, including your name, avatar, bio, social accounts, etc. to let other people know you.

(Option) Step 2: Configure two-factor authentication​

You can take GitHub Document: Configuring two-factor authentication for reference.

Step 3: Install Git​

If you don't have Git installed, you can download Git at www.git-scm.com.

If you need additional assistance in installing Git, you can find more information in the ProGit chapter on installing Git.

Step 4: Set your Git name and email​

Run the following commands in the terminal to set your email address and your name, which will be visible in your commits of Pull Request:

git config --global user.email "Your Email"
git config --global user.name "Your Name"

Step 5: Set up your text editor​

Run the following command to set up your favorite editor, which will be used to open and edit your files with Git:

git config --global core.editor "vim"

For more editors, such as Visual Studio Code, Sublime Text, and TextMate, see the GitHub Document.

Step 6: Learn about GitHub flow​

Follow this document to learn about the GitHub flow, including how to create a branch, make changes, create a pull request, address review comments, and merge the pull request.

Commit Conventions​

We have one git commit message template for coding contributions. You can download the file and run the following command to apply it globally:

git config --global commit.template .gitmessage

We have marked the important notes in the above template. For more on how to write a good commit message, you can read this blog: https://cbea.ms/git-commit/.

If you need to rewrite the most recent commit message, please use git commit --amend command, and see more on GitHub Documentation, but it doesn't support our customized message template.

GitHub Label System​

Description of the labels:

#Priority
    priority: Urgent - This should be dealt with ASAP. Not fixing this issue would be a serious error.
    priority: High - After critical issues are fixed, these should be dealt with before any further issues.
    priority: Medium - This issue may be useful, and needs some attention.
    priority: Low - This issue can probably be picked up by anyone looking to contribute to the project, as an entry fix

#Type
    type: Announcement - New Release, Events, Blog and more
    type: Proposal - Proposals of major changes to Apache Cloudberry
    type: Enhancement - New feature or request, ideas
    type: Question - Ask the community for help
    type: Documentation - Improvements or additions to documentation
    type: Bug - Something isn't working
    type: Refactoring - A code change that neither fixes a bug nor adds a feature
    type: Testing - Adding missing tests or correcting existing tests
    type: Security - Vulnerability disclosure or Fixing security issue
    type: Backport - Backport compitable related issues or PRs
    type: Pipeline - CICD and development pipeline

#Status
    status: Await triage - This issue needs triage.
    status: In Progress - This issue is being worked on, and has someone assigned.
    status: Not planned - Including Duplicate, Invalid and wontfix issues.
    status: Completed - This label means issues are done, closed, fixed or resovled.

#Standard
    help wanted - Extra attention is needed
    good first issue - Good for newcomers

If you add new labels, please follow the format prefix-name: type.

GitHub Issues or GitHub Discussions​

We use GitHub Issues as a bug report system and work tracking, use GitHub Discussions for asking questions and answering, share ideas for new features, and share proposals for Apache Cloudberry.

If you find problems and issues with code in Apache Cloudberry core, welcome to report to GitHub Issues.

If you want to ask for help, answer questions, share your new ideas for features, and get feedback for your proposal, please create new discussions directly.

Advanced Usage in GitHub​

In addition to the plain text and basic writing and formatting syntax, we can use more formats to communicate clearly in the GitHub pull requests, issues and comments, such as tables, diagrams, task lists and more, please refer to GitHub Documentation for details.

Acronyms and Abbreviations​

We often use some acronyms and abbreviations for the code review, and comments in our daily GitHub communications. We collect some popular words to help you leverage them as part of an effective code review process in the Apache Cloudberry community.

Learning Materials​

• Git Cheat Sheet
• Git Document