Guide to creating GitHub Issues and Pull Requests for OSS Contribution.
About the contribution guide for our OSS projects, please see the guide.
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 discuss 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 maintainers 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.
You should configure your Git client to sign commits. Pleas see Commit Signing.
Please add a newline at the end of file. Note that this doesn't mean add an empty line at the end of file.
The mark ⛔ means the file misses a newline at the end of file.
No newline at end of file
If you use VSCode, we recommend setting "files.insertFinalNewline": true.
https://stackoverflow.com/questions/44704968/visual-studio-code-insert-newline-at-the-end-of-files
Reference: Why should text files end with a newline?
Allowing changes to a pull request branch created from a fork
You should allow maintainers to push commits to your pull requests so that maintainers can collaborate with you well.
You can't allow maintainers to push commits to your pull requests if fork repositories belong to not GitHub User but GitHub Organization. This is the limitation of GitHub. So you should fork repositories into your GitHub User Account instead of GitHub Organization.
For simple questions or bugs, try asking AI tools such as DeepWiki or Claude Code. You may be able to resolve issues much faster without waiting for a maintainer’s response.
Sharing AI-generated investigation results or proposed fixes in an issue can also help maintainers. Rather than leaving everything to maintainers, actively using AI to investigate problems and showing a cooperative attitude can make it easier to receive support from them.
Whether AI tools are allowed naturally depends on each OSS project’s policy, but in OSS projects maintained by @suzuki-shunsuke, they are generally not restricted. Many of the projects maintained by @suzuki-shunsuke can be queried via DeepWiki:
- https://deepwiki.com/suzuki-shunsuke
- https://deepwiki.com/aquaproj
- https://deepwiki.com/csm-actions
- https://deepwiki.com/lintnet
Have AI review your issues and pull requests to check whether all necessary information is included and to improve their overall quality. The questions AI asks you to clarify are often the same things maintainers would want to confirm.
When using AI to create issues or pull requests, clearly disclose that AI was used. For example, you can add an AI agent as a co-author in commits or explicitly note when quoting AI-generated responses.
Before sharing AI-generated content, review it carefully and take responsibility for it. If maintainers ask questions about the content, responding with “I don’t know because it was generated by AI” is not acceptable.