Skip to content

Latest commit

 

History

History
160 lines (106 loc) · 6.91 KB

CONTRIBUTING.md

File metadata and controls

160 lines (106 loc) · 6.91 KB
Raw

CONTRIBUTING

❤❤❤🎉 Thank you for considering to contribute to this project! 🎉❤❤❤

The following is a set of guidelines that we ask you to follow when you contribute to this project.

Index

tl;dr

  • 📕 Please read this Guideline in its entirety once, if at least to check the headings.
  • 🙋 Please be nice, and please be aware that we are not providing this software as a hobby.
  • 💬 Open-ended questions and inquiries go to Discussions.
  • 🖥️ Actionable, specific technical questions go to Issues.
  • 📝 Please always include (pseudo)code for any technical questions/issues.
  • 🔒 Issues, PR, and other posts may be closed or not addressed if you do not follow these guidelines

Please Be Nice

Main source; if wordings differ, the main source supersedes this copy

Please be nice when you contact us.

We are very glad that you find this project useful, and we intend to provide software that help you.

You do not have to thank us, but please bare in mind that this is an opensource project that is provided as-is. This means that we are NOT obligated to support you, work for you, do your homework/research for you, or otherwise heed to you needs.

We do not owe you one bit of code, or a fix, even if it's a critical one.

We write software because we're curious, we fix bugs because we have integrity.

But we do not owe you anything. Please do not order us to work for you. We are not your support staff, and we are not here to do your research. We are willing to help, but only as long as you are being nice to us.

Please Read The Examples First

Main source; if wordings differ, the main source supersedes this copy

On most of the projects that we provide, we have example test code available, most likely in the examples/ directory. Before asking questions or filing issues, please make sure to take a look at the examples.

Specifically for Go projects, please first look for files with names *_example_test.go, which contain the runnable example code.

If the examples do not solve your problems, feel free to proceed with your report. If there are missing examples or inaccuracies, please do not hesitate to contact us.

Please Use Correct Medium (GitHub Issues / Discussions)

Main source; this is a specialized version copied from the main source

This project uses GitHub Issues to deal with technical issues including bug reports, proposing new API, and otherwise issues that are directly actionable.

Inquiries, questions about the usage, maintenance policies, and other open-ended questions/discussions should be posted to GitHub Discussions.

Please Include (Pseudo)code for Any Technical Issues

Main source; if wordings differ, the main source supersedes this copy

Your report should contain clear, concise description of the issue that you are facing. However, at the same time please always include (pseudo)code in report.

English may not be your forte, but we all should speak the common language of code. Rather than trying to write an entire essay or beat around the bush, which will more than likely cost both you and the maintainers extra roundtrips to communicate, please use code to describe exactly what you are trying to achieve.

Good reports should contain (in order of preference):

  1. Complete Go-style test code.
  2. Code snippet that clearly shows the intent of your code.
  3. Pseudocode that shows how you would want the API to work.

As we are dealing with code, ultimately there is no better way to convey what you are trying to do than to provide your code.

Please help us help you by providing us with a reproducible code.

Reviewer/Reviewee Guidelines

If you are curious about what what gets reviewed and why some decisions are made the way they are, please read this document to get some insight into the thinking process.

Brown M&M Clause

If you came here from an issue/PR template, please make sure to delete the section on "Contribution Guidelines" from the template.

Failure to do so may result in the maintainers assuming that you have not fully read the guidelines.

(Reference)

Pull Requests

Branches

vXXX branches

Stable releases, such as v1, v2, etc. Please do not work against these branches. Use the develop/vXXX branches instead.

develop/vXXX branches

Development occurs on these branches. If you are wishing to make changes against v2, work on develop/v2 branch.

When you make a PR, fork this branch, make your changes and create a PR against these development branches.

sequenceDiagram
  autonumber
  participant v1/v2/..
  participant develop/v1/v2/..
  participant feature_branch
  develop/v1/v2/..->>feature_branch: Fork development branch to your feature branch
  Note over feature_branch: Work on your feature
  feature_branch->>develop/v1/v2/..: File a PR against the development branch
  develop/v1/v2/..->>v1/v2/..: Merge changes
Loading

Generated Files

All files with file names ending in _gen.go are generated by a tool. These files should not be modified directly. Instead, find out the tool that is generating the file by inspecting the file. Usually the tool that generated the file is listed in the comment section at the top of the file.

Usually these files are generated based on a rule file (such as a YAML file). When you craft a pull request, you should include both changes to the rule file(s) and the generated file(s). The CI will run go generate and make sure that there are no extra diffs that have not been committed.

Test Cases

In general any code change must be accompanied with test case.

It is obviously very important to test the functionality. But adding test cases also gives you the opportunity to check for yourself how the new code should/can be used in practice. Test cases also act as a great way to communicate any assumptions or requirements that your code needs in order to function properly.