github.com/lestrrat-go/jwx/v2@v2.0.21/.github/CONTRIBUTING.md (about)

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