GitHub repository user guide

[kangz12345]

This guide is for the repository users. Please follow the rules for consistency and efficiency.

1. Issues

1.1. Motivation

• It helps tracking, referencing and dealing with the issues
• It includes bug reports, new feature proposals, or any opinions on this project
• It also provides some features for project management, e.g., milestones and projects

1.2. Guides

1.2.1. Labels

• Use appropriate labels which categorize the issue
• One can change the labels even if he or she is not the author (it leaves history)

1.2.2. Assignees

• You can assign some people to the issue, who will take care of the issue
• If the author does not assign it, the repository maintainers will do
• The assignee(s) should keep track on the issue and make progress on it

1.2.3. Projects

• GitHub projects can be linked and it helps tracking the task status
• Link appropriate projects and mark its status and iteration (it will appear after you create an issue)

1.2.4. Milestones

• You can see the milestones of this repository on the Issues page
• It helps individual task management with due dates
• Link any relevant milestones to the issue

1.2.5. Template

• Choose a right template for the issue
• Templates help describing the issue with enough information

1.2.6. Title

• Title should be concise, informative and readable
• Title format is not restricted (e.g., imperatives, nouns, etc. are all okay)

2. Pull requests

2.1. Motivation

• You can make changes to the main or develop branch via pull requests only (you cannot directly push commits to the protected branches)
• Each pull request is an article with code changes, based on a branch
• You should provide enough information about the code changes or you can mention an issue instead
• The other contributors will review your code

2.2. Guides

2.2.1. Branch

• You have to select the base and compare branch, i.e., you merge the compare branch onto the base branch
• Please do not change the base branch, which will be set to the default branch develop
• You have to push your local branch before making a pull request

2.2.2. Labels

• Use labels just like issues

2.2.3. Reviewers

• Assign reviewers who will review your code
• At least one reviewers must approve the pull request

2.2.4. Assignees

• In most cases, assign yourself because you will make your own pull requests

2.2.5. Projects

• Link GitHub projects just like issues

2.2.6. Milestones

• Link milestones just like issues

2.2.7. Closing keywords

• You can use closing keywords to link an issue and make it closed when the pull request is merged
• Do not use the closing keywords in commit messages

2.2.8. Title

• Use commit message style as it will be the merge commit message

2.3. Code review

Reviewer must review the codes thoroughly!

2.3.1. Conversation

• Reviewers can make conversations when they review the codes
• Every conversation should be resolved by the reviewer, not the author of the pull request

3. Discussions

3.1. Motivation

• It helps general communication for the project
• It is not for the development, use issues instead

3.2. Guides

3.2.1. Labels

• Use appropriate labels just like issues

3.2.2. Subjects

• If you want to talk about a specific feature or bug, consider using issues instead
• Discussion is for general communication, e.g., announcements, idea that are too abstract to be an issue, questions about the project, etc.

Overall

Language

We use English as this is an open source project.
It is often efficient since we use English for the codes as well.
Please do not be afraid of grammar or awkward expressions, and please let the author know when you found some language issues in the expressions.

Mention

• You can refer to any issues, pull requests or discussions using a "#", just like hashtags
• After type a "#", you can search by its number or title, e.g., this discussion is GitHub repository user guide #1
• You can mention a user with a "@" and the user name, e.g., @kangz12345

[BECATRUE]

I recommend to set the commit message template with reference to this.
It is not mandatory, but it helps you to write and read commit messages more neatly.