Skip to content

Latest commit

 

History

History
130 lines (89 loc) · 4.75 KB

git-workflow.md

File metadata and controls

130 lines (89 loc) · 4.75 KB

Git Workflow

This document is the best practice guide that contains the rules to follow when working with AsyncAPI repositories.

Overview

AsyncAPI uses a fork model for all community members, including maintainers. In this model, you push changes to your own working copy of the original (upstream) repository, and then create one or more pull requests (PRs) to incorporate changes from your fork to upstream. This unified workflow allows both members and external contributors to contribute through the same process, keeping the main repository branches clean.

Rules

Each contributor and maintainer in AsyncAPI must follow this workflow:

  • Work on forked repositories.
  • Create branches on the fork.
  • Avoid working directly on the master branch of the fork.
  • Create pull requests from the fork to the upstream repository.

Fork a repository

  1. On GitHub, navigate to the AsyncAPI repository you want to fork.
  2. In the top-right corner of the page, click Fork.
  3. Under Owner, select the dropdown menu and click an owner for the forked repository.
  4. Ensure that the Copy the DEFAULT branch only is selected.
  5. Click Create fork.

Clone the forked repository

  1. On GitHub, navigate to the forked repository.

  2. Click the Code button.

  3. Copy the URL.

  4. In the terminal, navigate to the directory where you want to clone the repository.

  5. Run the following command:

    # Command syntax
git clone URL

# Examples
git clone https://github.com/YOUR-USERNAME/asyncapi-community.git
git clone [email protected]:YOUR-USERNAME/asyncapi-community.git

Configure your fork

Configure a remote repository that points to the upstream repository (from which you forked). This allows you to synchronize changes you make on the fork with the original repository. Configuration can be done manually or using the GitHub UI.

Tip

If you perform fork configuration for the first time, it is recommended to do it manually to understand all the steps.

Next time you can write a script to synchronize master branch of your fork with the master branch of upstream git repository. Check this script as an example to get started.

Manual configuration

In the terminal, navigate to your fork's location and perform the following steps:

  1. Check the current list of remotes:

    # Command
git remote -v

# Output
origin  https://github.com/YOUR-USERNAME/FORK-NAME.git (fetch)
origin  https://github.com/YOUR-USERNAME/FORK-NAME.git (push)

  2. Add the upstream repository. In other words, point to the main project located in the AsyncAPI GitHub organization:

    # Command
git remote add upstream https://ORIGINAL-OWNER/ORIGINAL-REPOSITORY-NAME.git

# Example
git remote add upstream https://github.com/asyncapi/community.git

    Verify that the upstream has been added:

    git remote -v

# Output
origin https://github.com/YOUR-USERNAME/FORK-NAME.git (fetch)
origin https://github.com/YOUR-USERNAME/FORK-NAME.git (push)
upstream       [email protected]:asyncapi/asyncapi-community.git (fetch)
upstream       [email protected]:asyncapi/asyncapi-community.git (push)

  3. Fetch changes from the upstream:

    # Command
git fetch upstream master

  4. Set the master branch of your fork to track the master branch of the upstream repository:

    git branch -u upstream/master master

    Verify with git branch -vv:

    * master           c2226e0 [upstream/master] Update the README.md document

By setting the upstream branch, you can simplify your workflow. For example, you can use git pull and git push without specifying the remote and branch names, as Git will automatically use the upstream branch you have set. This is particularly useful when you frequently need to synchronize your local branch with a remote branch.

Using GitHub UI

You can follow the steps from the GitHub documentation to sync your fork and keep it up-to-date with the upstream repository.

Start Contributing

  1. Create a branch on your fork.

  2. Commit changes with clear messages. Use the Conventional Commits format.

  3. Push changes to your fork:

    git push -u origin BRANCH-NAME

    For subsequent pushes, use the shorthand:

    git push

  4. Create a pull request from your branch of the fork repository to the master branch of the upstream repository and await review.