1# CONTRIBUTING
2
3❤❤❤🎉 Thank you for considering to contribute to this project! 🎉❤❤❤
4
5The following is a set of guidelines that we ask you to follow when you contribute to this project.
6
7# Index
8
9* [tl;dr](#tldr)
10* [Please Be Nice](#please-be-nice)
11* [Please Use Correct Medium (GitHub Issues / Discussions)](#please-use-correct-medium-github-issues--discussions)
12* [Please Include (Pseudo)code for Any Technical Issues](#please-include-pseudocode-for-any-technical-issues)
13* [Brown M&M Clause](#brown-mm-clause)
14* [Pull Requests](#pull-requests)
15 * [Branches](#branches)
16 * [Generated Files](#generated-files)
17 * [Test Cases](#test-cases)
18
19# tl;dr
20
21* 📕 Please read this Guideline in its entirety once, if at least to check the headings.
22* 🙋 Please be nice, and please be aware that we are not providing this software as a hobby.
23* 💬 Open-ended questions and inquiries go to [Discussions](https://github.com/lestrrat-go/jwx/discussions).
24* 🖥️ Actionable, specific technical questions go to [Issues](https://github.com/lestrrat-go/jwx/issues).
25* 📝 Please always include (pseudo)code for any technical questions/issues.
26* 🔒 Issues, PR, and other posts may be closed or not addressed if you do not follow these guidelines
27
28# Please Be Nice
29
30Please be nice when you contact us.
31
32We are very glad that you find this project useful, and we intend to provide software
33that help you.
34
35You do not have to thank us, but please bare in mind that this is an opensource project that is provided **as-is**.
36This means that we are **NOT** obligated to support you, work for you, do your homework/research for you,
37or otherwise heed to you needs.
38
39We do not owe you one bit of code, or a fix, even if it's a critical one.
40
41We write software because we're curious, we fix bugs because we have integrity.
42
43But we do not owe you anything. Please do not order us to work for you.
44We are not your support staff, and we are not here to do your research.
45We are willing to help, but only as long as you are being nice to us.
46
47# Please Use Correct Medium (GitHub Issues / Discussions)
48
49This project uses [GitHub Issues](https://github.com/lestrrat-go/jwx/issues) to deal with technical issues
50including bug reports, proposing new API, and otherwise issues that
51are directly actionable.
52
53Inquiries, questions about the usage, maintenance policies, and other open-ended
54questions/discussions should be posted to [GitHub Discussions](https://github.com/lestrrat-go/jwx/discussions).
55
56# Please Include (Pseudo)code for Any Technical Issues
57
58Your report should contain clear, concise description of the issue that you are facing.
59However, at the same time please always include (pseudo)code in report.
60
61English may not be your forte, but we all should speak the common language of code.
62Rather than trying to write an entire essay or beat around the bush, which will
63more than likely cost both you and the maintainers extra roundtrips to communicate,
64please use code to describe _exactly_ what you are trying to achieve.
65
66Good reports should contain (in order of preference):
67
681. Complete Go-style test code.
691. Code snippet that clearly shows the intent of your code.
701. Pseudocode that shows how you would want the API to work.
71
72As we are dealing with code, ultimately there is
73no better way to convey what you are trying to do than to provide
74your code.
75
76Please help us help you by providing us with a reproducible code.
77
78# Brown M&M Clause
79
80If you came here from an issue/PR template, please make sure to delete
81the section on "Contribution Guidelines" from the template.
82
83Failure to do so may result in the maintainers assuming that you have
84not fully read the guidelines.
85
86[(Reference)](https://www.insider.com/van-halen-brown-m-ms-contract-2016-9)
87
88# Pull Requests
89
90## Branches
91
92### `vXXX` branches
93
94Stable releases, such as `v1`, `v2`, etc. Please do not work against these branches.
95Use the `develop/vXXX` branches instead.
96
97### `develop/vXXX` branches
98
99Development occurs on these branches. If you are wishing to make changes against
100`v2`, work on `develop/v2` branch.
101
102When you make a PR, fork this branch, make your changes and create a PR against
103these development branches.
104
105```mermaid
106sequenceDiagram
107 autonumber
108 participant v1/v2/..
109 participant develop/v1/v2/..
110 participant feature_branch
111 develop/v1/v2/..->>feature_branch: Fork development branch to your feature branch
112 Note over feature_branch: Work on your feature
113 feature_branch->>develop/v1/v2/..: File a PR against the development branch
114 develop/v1/v2/..->>v1/v2/..: Merge changes
115```
116
117## Generated Files
118
119All files with file names ending in `_gen.go` are generated by a tool. These files
120should not be modified directly. Instead, find out the tool that is generating the
121file by inspecting the file. Usually the tool that generated the file is listed
122in the commect section at the top of the file.
123
124Usually these files are generated basede on a rule file (such as a YAML file).
125When you craft a pull request, you should include both changes to the rule file(s)
126and the generated file(s). The CI will run `go generate` and make sure that
127there are no extra `diff`s that have not been commited.
128
129## Test Cases
130
131In general any code change must be accompanied with test case.
132
133It is obviously very important to test the functionality. But adding test cases
134also gives you the opportunity to check for yourself how the new code should/can
135be used in practice. Test cases also act as a great way to communicate any
136assumptions or requirements that your code needs in order to function properly.
137
138
View as plain text