docs: make steps in git workflow more beginner-friendly #1772
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bandantonio
requested review from
quetzalliwrites,
derberg,
asyncapi-bot-eve and
thulieblack
as code owners
1 task
|
@derberg can you help review, if we missed a step |
derberg
reviewed
Mar 14, 2025
git-workflow.md
Outdated
|
|
||
| Each contributor and maintainer in AsyncAPI must follow this workflow: | ||
| AsyncAPI uses a fork model to allow contributions to the organization's repositories. In this model, you push changes to your own working copy (a fork, a so-called `origin`) of the original repository (a so-called `upstream`), and then create one or more pull requests (PRs) to incorporate changes from the `origin` to `upstream`. This unified workflow allows both members and external contributors to contribute through the same process, keeping the main repository branches clean. |
There was a problem hiding this comment.
Suggested change
| AsyncAPI uses a fork model to allow contributions to the organization's repositories. In this model, you push changes to your own working copy (a fork, a so-called `origin`) of the original repository (a so-called `upstream`), and then create one or more pull requests (PRs) to incorporate changes from the `origin` to `upstream`. This unified workflow allows both members and external contributors to contribute through the same process, keeping the main repository branches clean. | |
| AsyncAPI uses a fork model for all community members, including maintainers. In this model, you push changes to your own working copy (a fork, a so-called `origin`) of the original repository (a so-called `upstream`), and then create one or more pull requests (PRs) to incorporate changes from the `origin` to `upstream`. This unified workflow allows both members and external contributors to contribute through the same process, keeping the main repository branches clean. |
There was a problem hiding this comment.
(a fork, a so-called
origin)
you need to change it somehow - it sounds like origin is the same as fork but it is not
origin is the remote version of repo - opposing the local copy (clone)
so upstream, if somebody clones (asyncapi bot) the upstream, it operates on local version, on clone - and pushes it to origin, in this case upsteam is origin
so fork = origin && upstream = origin
git-workflow.md
Outdated
Comment on lines
91
to
97
| ```bash | ||
| # Command | ||
| git fetch upstream BRANCH-NAME | ||
|
|
||
| # Example | ||
| git fetch upstream master | ||
| ``` |
There was a problem hiding this comment.
Suggested change
| ```bash | |
| # Command | |
| git fetch upstream BRANCH-NAME | |
| # Example | |
| git fetch upstream master | |
| ``` | |
| ```bash | |
| # Command | |
| git fetch upstream master | |
| ``` |
in our case it will always be master - because of ci/cd complex setup, we are not able to enable main
git-workflow.md
Outdated
|
|
||
| In case you are a contributor who suggests minor changes using GitHub UI, it is recommended to use a [Pull bot](https://probot.github.io/apps/pull). This bot keeps your fork up to date by creating and merging a pull request with latest changes into the `master `branch of your fork. | ||
| For minor changes via GitHub UI, use a [Pull bot](https://probot.github.io/apps/pull) to keep your fork up to date. |
There was a problem hiding this comment.
so many years after writing this first version of the document, not sure we should recommend pullbot
now there is a native functionality in GH, that allows you to update your fork with upstream with one click
I stopped using pull bot few years back 😄
git-workflow.md
Outdated
|
|
||
| 4. Create a pull request from the branch of your forked repository to the `master` branch of the upstream repository and wait for the maintainers' review. | ||
| 4. Create a pull request from your branch of the `origin` repository to the `master` branch of the `upstream` repository and await review. |
There was a problem hiding this comment.
Suggested change
| 4. Create a pull request from your branch of the `origin` repository to the `master` branch of the `upstream` repository and await review. | |
| 4. Create a pull request from your branch of the fork repository to the `master` branch of the `upstream` repository and await review. |
git-workflow.md
Outdated
| git remote add upstream https://github.com/{original-owner}/{original-repository}.git | ||
| ``` | ||
| See the example: | ||
| 2. Add the `upstream` repository: |
There was a problem hiding this comment.
Suggested change
| 2. Add the `upstream` repository: | |
| 2. Add the `upstream` repository. In other words, point to main project located in AsyncAPI GitHub organization: |
derberg
approved these changes
Mar 31, 2025
|
/rtm |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
When expanding our Community documentation (#1622) we came across the situation that multiple documents (#1725, #1730) describe git workflow as a prerequisite to start contributing to community repos.
It was decided to update the workflow document with more user-friendly instructions and link back to this document while removing redundant sections from other documents that mention git workflow in any context.
Related issue(s)
See also #1622 #1725 #1730