From b9eb2b9adbd1fece39dc6d623037652852efb66a Mon Sep 17 00:00:00 2001 From: Ezinne Anne Emilia Date: Mon, 17 Feb 2025 15:27:44 +0100 Subject: [PATCH] docs: expand community docs: contributor - simple contribution flow and recommended tools --- making-a-contribution.md | 77 ++++++++++++++++++++++++++++++++++++++++ recommended-tools.md | 12 +++++++ 2 files changed, 89 insertions(+) create mode 100644 making-a-contribution.md create mode 100644 recommended-tools.md diff --git a/making-a-contribution.md b/making-a-contribution.md new file mode 100644 index 000000000..b6b48422b --- /dev/null +++ b/making-a-contribution.md @@ -0,0 +1,77 @@ +# Contributor - Simple Contribution Flow +This article covers how to make a contribution on AsyncAPI. It walks you through the basic contribution flow and workflow processes you need to setup in order to make a contribution. + +## Contents +- [Contributor - Simple Contribution Flow](#contributor---simple-contribution-flow) + - [Contents](#contents) + - [Making a contribution](#making-a-contribution) + - [Setting up a workflow](#setting-up-a-workflow) + - [Setting up the `master` branch](#setting-up-the-master-branch) + - [Setting up a new branch](#setting-up-a-new-branch) + - [Making a pull request](#making-a-pull-request) + - [Making further commits](#making-further-commits) + - [Additional Information](#additional-information) + +## Making a contribution +You are welcome to making a contribution at AsyncAPI. We would love to get your suggestions, improvements, and ideas. You are encouraged to make quality contributions either by making a PR(Pull Request) for an already existing issue or creating an issue. To make a successful contribution, you are required to work on a forked repository and create a branch on the forked repository where you can make your changes(do not work directly on the `master` branch). + +## Setting up a workflow +### Setting up the `master` branch +- Fork the repository by clicking on the fork icon +- Clone the forked repo in your local terminal +```git clone ``` +- Run ```git remote -v```. This will list the URLs of the remote repository for your fork. +The result is as follows: + ``` + origin https://github.com/{your-username}/{your-fork}.git (fetch) + origin https://github.com/{your-username}/{your-fork}.git (push) + ``` + + See the example: + ``` + origin https://github.com/i000000/asyncapi.git (fetch) + origin https://github.com/i000000/asyncapi.git (push) + ``` +- Run ```git remote add upstream https://github.com/{original-owner}/{original-repository}.git``` + - This adds a new remote named `upstream` to your local repository. + - The `upstream` name refers to the original repository while `origin` refers to the forked repository. + - The `https://github.com/{original-owner}/{original-repository}.git` refers to the URL of the main repo. + + See the example: ```git remote add upstream https://github.com/asyncapi/asyncapi.git``` + +- Run ```git fetch upstream master``` to download the latest changes from the master branch of the upstream remote (the original repository you forked from). +- Set up the local branch to track the remote branch from the upstream repo: ```git branch -u upstream/master master``` +- Run ```git branch -vv``` to verify that your local `master` branch points to the `upstream/master` branch. +The result is similar to the following: +``` +* master c2226e0 [upstream/master] Update the README.md document +``` + +### Setting up a new branch +Before you begin to make changes, create a new branch +- Run `git checkout -b ` + +## Making a pull request +After making contributions and you are set to make a PR. + +- Run `git add ` if you created a new file as part of your changes and commit with a meaningful message. `git commit -m "Meaningful commit message"`. Else, commit your changes with `git commit -am "Meaningful commit message"`. +- Push the changes + +``` +git push --set-upstream origin +``` +- Make a pull request and wait for the maintainers to review. + +## Making further commits +Normally, when a maintainer requests changes on your PR, there may have been previous commits from other contributors on that repository. Before you begin to add those changes, make sure you sync your branches (both the master and custom branch you are using). +After doing that, in your local machine terminal run `git pull` to download and merge the changes to your local machine then you can start making the changes. + +To make further commits on that same repository and branch. +Simply run, +- `git add ` and `git commit -m "Meaningful commit message"` (if you created a new file). +- But if you are making modifications, run `git commit -am "Meaningful commit message"`. +- Run `git push` to push your changes. + +## Additional Information +- [Git workflow document](https://github.com/asyncapi/community/blob/master/git-workflow.md) +- [Conventional commit messages](https://github.com/asyncapi/website/blob/master/CONTRIBUTING.md) diff --git a/recommended-tools.md b/recommended-tools.md new file mode 100644 index 000000000..1288a0458 --- /dev/null +++ b/recommended-tools.md @@ -0,0 +1,12 @@ +# Contributor - Recommended Tools +This article covers the recommended tools you should have as a contributor. With these tools, you can set up workflows and begin making contributions. + +These are the recommended tools you need:- +- A laptop or a desktop computer capable of running tools which you would use for contribution. +- A stable internet connection to fork, clone a repo, make changes, and submit a PR. +- Install [Git](https://git-scm.com)- a version control system. +- [A GitHub account](https://github.com). AsyncAPI hosts all its project source code and dependencies on GitHub. You'll need a GitHub account to create issues, fork the repository, submit pull requests, and more. If you're new to GitHub, familiarize yourself with [basic GitHub functionalities and workflows](https://docs.github.com/en/get-started). +- A code editor, such as [VS Code](https://code.visualstudio.com). +- [Nodejs and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). So you can run the website locally on your machine. +- A working browser such as Google Chrome, Firefox or Microsoft Edge where you can preview your changes. +- Lastly, you need a command line terminal where you can run commands. You can use your local command line or the terminal in VSCode. \ No newline at end of file