This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new cc3dedb fix: update contributing guide (#888)
cc3dedb is described below
commit cc3dedbf69247ce671aa02cc95f4cd345efe7539
Author: Navendu Pottekkat <[email protected]>
AuthorDate: Thu Feb 24 06:47:14 2022 +0530
fix: update contributing guide (#888)
Signed-off-by: Navendu Pottekkat <[email protected]>
---
website/docs/general/contributor-guide.md | 123 ++++++++++++++++++------------
1 file changed, 74 insertions(+), 49 deletions(-)
diff --git a/website/docs/general/contributor-guide.md
b/website/docs/general/contributor-guide.md
index c20c84a..dd35fb7 100644
--- a/website/docs/general/contributor-guide.md
+++ b/website/docs/general/contributor-guide.md
@@ -9,45 +9,39 @@ keywords:
description: This article is a set of guidelines for Apache APISIX
contributors, including things that a contributor can do and how to do it well.
---
-Please feel free to report bugs, submit suggestions, or submit PRs according
to this guide.
+Please follow this guide to [report bugs](#submitting-an-issue), [submit
suggestions](#submitting-an-issue), or [submit PRs](#open-a-pull-request).
-## Submit an issue
+## Submitting an Issue
-1. Before submitting your issues, please go through a comprehensive search to
make sure the problem cannot be solved just by searching.
+Before submitting an issue, try solving the problem through a comprehensive
search.
-2. Check the Issue List to make sure the problem is not repeated.
+[Open issues](https://github.com/apache/apisix/issues) and the [discussions
forum](https://github.com/apache/apisix/discussions) are good places to search
for solutions before opening an issue.
-3. Create a new issue and choose the type of issue.
+1. Check the [open issues](https://github.com/apache/apisix/issues) to avoid
duplication.
-4. Define the issue with a clear and descriptive title.
+2. Create a [new issue](https://github.com/apache/apisix/issues/new/choose)
and choose the type of issue.
-5. Fill in necessary information according to the template.
+3. Define the issue with a clear and descriptive title.
-6. Choose a label after the issue is created.
+4. Fill in necessary information according to the template.
-7. Please pay attention to your issue, you may need to provide more
information during discussion.
+5. Engage in the discussions in the issue and provide more information if
necessary.
-## Developer Flow
+## Choosing an Issue to Work On
-### Fork repo
+You can also contribute by fixing one of the [open
issues](https://github.com/apache/apisix/issues).
-Fork the Apache APISIX repo to your repo to work, then set proper upstream.
+1. Once you have chosen an issue to work on or [opened a new
issue](#submitting-an-issue), please comment on the issue and ask a [Committer
or PMC](/team) to assign it to you.
-```sh
-git remote add upstream https://github.com/apache/apisix.git
-```
-
-### Choose an issue
+2. Please check to see if the issue is already being worked on and indicate
when you will be able to complete it.
-1. Please choose your target issue. If it is a new issue discovered or a new
function enhancement to offer, please create an issue and set the right label
for it.
+3. Connect with a [Committer or PMC](/team) for providing feedback on your
issue and reviewing your PR.
-2. After choosing the relevant issue, please reply with a deadline to indicate
that you are working on it.
+### Good First Issues
-3. Find a mentor from the Team page and your mentor will give you feedback
about your PR or issue in time.
+Issues labelled "good first issues" are low hanging fruits that are easy to
fix. These issues can help you make your first contributions to Apache APISIX®.
-#### **Good First Issues**:
-
-Good First Issue curates easy pickings from this project and helps you make
your first contribution to Apache APISIX®.
+The list below contains such issues spanning across all the repos in Apache
APISIX®.
- [Apache
APISIX®](https://github.com/apache/apisix/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
- [Apache APISIX® Ingress
Controller](https://github.com/apache/apisix-ingress-controller/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
@@ -58,55 +52,86 @@ Good First Issue curates easy pickings from this project
and helps you make your
- [Apache APISIX® Java Plugin
Runner](https://github.com/apache/apisix-java-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
- [Apache APISIX® Go Plugin
Runner](https://github.com/apache/apisix-go-plugin-runner/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
-### Create your branch
+## Git Flow
+
+To contribute code or documentation, setup your local machine for development.
+
+### Fork the repo and clone your fork
-Switch to your forked master branch, pull codes from upstream, then create a
new branch.
+Fork the [Apache APISIX repo](https://github.com/apache/apisix/) and clone
your fork to your local machine.
```sh
-$ git checkout master
-$ git pull upstream master
-$ git checkout -b IssueNo
+git clone https://github.com/your-username/apisix.git
```
-Notice: We will merge PR using squash, commit logs will be different from
upstream if you use one older branch.
+### Add 'upstream' repo to list of remotes
-### Coding
+Check to see if the upstream repo has been configured by listing the remotes.
-1. Please obey the Code of Conduct during the process of development and
finish the check before submitting the pull request.
+```sh
+git remote -v
+```
-2. Then push codes to your fork repo.
+If not, you can add the upstream remote.
```sh
-$ git add modified-file-names
-$ git commit -m 'commit message'
-$ git push origin issueNo
+git remote add upstream https://github.com/apache/apisix.git
```
-### Submit PR
+Learn more about Git and GitHub flow by following the [GitHub
Docs](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
-1. Send a pull request to the master branch.
+**Note**: Setup your name and email address to make sure that your ID shows up
in the contributor list.
-2. The mentor will do a codes review before discussing some details (including
the design, the implementation, and the performance) with you.
+```sh
+git config --global user.name "full name"
+git config --global user.email "mail address"
+```
-3. Also make sure that the pull request title has a semantic prefix like
`fix:` or `feat:` or any other [conventional commit
types](https://github.com/commitizen/conventional-commit-types/blob/master/index.json).
+### Create your branch
-4. Then congratulate you to be an official contributor of Apache APISIX.
+To keep your local fork up to date, fetch and rebase with the upstream remote.
-### Delete branch
+```sh
+git fetch upstream
+git checkout master
+git rebase upstream/master
+git push origin master
+```
-You can delete the remote branch (origin/IssueNo) and the local branch
(IssueNo) associated with the remote branch (origin/IssueNo) after the mentor
merged the PR into the master branch.
+Then, to make changes, create a new branch in your local fork.
```sh
-$ git checkout master
-$ git branch -d IssueNo
-$ git push origin --delete issueNo
+git checkout -b issue-no
```
-### Notice
+**Note**: The commits in a PR are squashed before merging. This could result
in commit logs different from upstream if you are using an older branch.
+
+### Commiting your changes
+
+Contributors are expected to adhere to the [Code of
Conduct](https://www.apache.org/foundation/policies/conduct.html) throughout
the process.
-Please note that to show your ID in the contributor list, please DO NOT forget
to set the configurations below:
+Once you make the changes, commit the files and push the changes to your fork.
```sh
-$ git config --global user.name "username"
-$ git config --global user.email "mail address"
+$ git add modified-file-names
+$ git commit -m 'commit message'
+$ git push origin issue-no
```
+
+### Open a pull request
+
+Once you have your changes pushed to your fork, it is time to start the
process of merging it to upstream by opening a pull request.
+
+See [GitHub
flow](https://docs.github.com/en/get-started/quickstart/github-flow#create-a-pull-request)
for detailed instructions on making a pull request.
+
+1. Open a pull request to the master branch.
+
+2. Make sure that the pull request title has a semantic prefix like `fix:` or
`feat:` or any other [conventional commit
types](https://github.com/commitizen/conventional-commit-types/blob/master/index.json).
+
+3. Reach out to your mentor for starting the review process.
+
+4. Engage in discussions and provide clarifications to reviewers' questions.
+
+5. Wait for your PR to be approved and merged.
+
+6. Congratulate yourself for being an official contributor of Apache APISIX®!
