Guide to creating GitHub Issues and Pull Requests for OSS Contribution
- Read the project's contribution guide
- Use English
- Create an Issue before creating a Pull Request
- Use Issue Templates
- Describe the detail as much as possible. Don't neglect to explain
- Use GitHub Flavored Markdown properly
- Describe WHY and Background in your Feature Request
- Write good
How to reproduce - Don't do force pushes after opening pull requests
- Separate commits that code was created or updated by command
- Related Articles
First, you should check and follow the project's contribution guide such as CONTRIBUTING.md.
If English is used in the project you should use English. For example, even if the project author is Japanese, you shouldn't use Japanese if English is used in the project.
Machine Translator such as DeepL would help you.
You should create an Issue and describe your proposal or a bug and disucss how to implement or how to solve the problem before creating a Pull Request. You can discuss the detail of the implementation in the Pull Request, but you should describe the background of the pull request in the Issue.
Of course, there are some exceptions such as fixing typo.
Using Issue Templates, maintainers can get the required information and communicate with you comfortably. If you ignore them, maintainers may misunderstand the issue or they would have to ask you some questions to get the required information.
If there is no issue template in the project, you should structure the description according to some common issue template.
The lack of information would make unneeded conversation and misunderstanding. It would help if you were careful maintainers can handle the Issue comfortably.
Especially, you should use fenced code blocks. Fenced code blocks make a comment easy to read. The readability of code without fenced block is terrible.
It would help if you described not only what is needed but also why this is needed and the background you think the feature is necessary.
If there is a workaround, you should describe it and why it isn't enough.
Sometimes your problem would be solved without new feature development.
You should write the following information.
- Environment
- OS (e.g. Windows, macOS, Ubuntu)
- Arch (e.g. amd64, arm64)
- tool versions: If multiple tools are used, you should write all tool versions
- Code
- command and result
Expected BehaviorandActual Behavior- Debug Log
If you try multiple versions, you should describe the result too.
Code and command should be minimum, reproducible, and executable.
Code unrelated to the issue should be removed.
Everyone should be able to execute the code and reproduce the problem according to How to reproduce.
Code shouldn't be partial because partial code isn't executable.
Private resources shouldn't be used in How to reproduce if it isn't needed.
For example, if you can reproduce the issue with public Docker images, you shouldn't use private Docker images.
Expected Behavior and Actual Behavior should be clear.
For example, a report such as an error occurs and the tool doesn't work is ambiguous.
If an error occurs, you should paste the command and standard (error) output.
A screenshot may also be helpful, but a text in the screenshot can't be copied so you should paste the output as text too.
After opening pull requests, you shouldn't do force pushes because force pushes make it difficult for maintainers to review the diff. And if maintainers push commits to pull requests, your force push may eliminate maintainers' commits. Instead of force pushes, you should push new commits, then maintainers can review the diff.
For example, when maintaiers request a change to you, if you push a new commit maintainers can review it easily, but if you do a force push, maintainers can't understand easily what is changed by force push so the review is difficult.
As an exception, if mantainers ask you to make commits history clean by rebasing, you should follow the request.
If you generate some codes by command, you should separate commits for the change with other changes. And you should show the command in the commit message. This makes changes easy to understand and review.