CONTRIBUTING.md

   1 # How to contribute
   2
   3 Thank you for using and contributing to StGit! This brief guide
   4 describes how to contribute bug reports, feature ideas, and code changes
   5 to the Stacked Git project.
   6
   7 ## Bugs
   8
   9 StGit is not bug-free software. If you think you may have found a bug,
  10 please visit the [issue tracker](https://github.com/stacked-git/stgit/issues)
  11 and search to see if an issue for the bug has already been created.
  12
  13 If a relevant issue already exists, you may want to subscribe to the
  14 issue so that you can be notified when the issue status changes. Also,
  15 you may want to add notes about the bug if your observations differ
  16 from the original issue.
  17
  18 If an existing issue does not match, then you are encouraged to create a
  19 new issue.
  20
  21 ### Creating an Issue
  22
  23 When creating an issue, please refer to this checklist. The goal is to
  24 capture the relevant information about your environment and the actions
  25 that triggered the bug needed to debug the problem.
  26
  27 Please include the following in StGit issue reports:
  28
  29 1. StGit version. Run `stg --version`. The output includes StGit, Git
  30    and Python versions--all three are important.
  31
  32 2. What StGit command(s) triggered the problem.
  33
  34 3. Details about the StGit stack and the Git repository.
  35
  36
  37 ## Features
  38
  39 Ideas for StGit features may be submitted on the [issue
  40 tracker][issue-tracker] for consideration and discussion. A proposed
  41 feature's value will be weighed against its reach to StGit users and its
  42 ongoing cost to StGit maintenance. High-reach, low-maintenance features
  43 are most likely to be accepted by StGit's maintainers.
  44
  45 And for a StGit feature to be realized, it needs to be implemented.
  46 While it is *possible* that another member of the StGit community will
  47 champion your idea, the more you contribute, the more likely the feature
  48 will get done. So writing test cases, specifying details about the
  49 feature, and writing working code are all helpful toward getting a
  50 feature into StGit.
  51
  52 [issue-tracker]: https://github.com/stacked-git/stgit/issues
  53
  54
  55 ## Code Changes
  56
  57 Code changes for bug fixes and features should be submitted as [pull
  58 requests][PR] to the [stgit repository][stgit-repo] on GitHub, with the
  59 following guidelines:
  60
  61 [PR]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
  62 [stgit-repo]: https://github.com/stacked-git/stgit
  63
  64 - Test cases! Please add test cases to the test suite in the `t`
  65   directory to verify any new or changed StGit behaviors. And run `make
  66   test` to ensure the test suite passes.
  67
  68 - Add a `Signed-off-by:` trailer to each commit message to indicate that
  69   certifies that you wrote or otherwise have the right to contribute the
  70   patch as open-source, according to the [Developers Certificate of
  71   Origin](#developers-certificate-of-origin-11). A `Signed-off-by:` line
  72   can be added to a patch by running `stg edit --sign`.
  73
  74 - Lint. Run `make lint` to ensure that the code meets the project's
  75   syntactic standards and passes static checks.
  76
  77 ### Developer's Certificate of Origin 1.1
  78
  79 By making a contribution to this project, I certify that:
  80
  81 (a) The contribution was created in whole or in part by me and
  82     I have the right to submit it under the open source
  83     license indicated in the file; or
  84
  85 (b) The contribution is based upon previous work that, to the
  86     best of my knowledge, is covered under an appropriate open
  87     source license and I have the right under that license to
  88     submit that work with modifications, whether created in
  89     whole or in part by me, under the same open source license
  90     (unless I am permitted to submit under a different
  91     license), as indicated in the file; or
  92
  93 (c) The contribution was provided directly to me by some other
  94     person who certified (a), (b) or (c) and I have not
  95     modified it.
  96
  97 (d) I understand and agree that this project and the
  98     contribution are public and that a record of the
  99     contribution (including all personal information I submit
 100     with it, including my sign-off) is maintained indefinitely
 101     and may be redistributed consistent with this project or
 102     the open source license(s) involved.
 103
 104 ### Checklist
 105
 106 - Each commit (patch) addresses a coherent topic.
 107 - `make lint` passes.
 108 - No commented-out code or unneeded files in commits.
 109 - Each commit has a meaningful commit message.
 110 - Each commit has a `Signed-off-by: Your Name <you@example.com` trailer.
 111 - Tests are added/modified that cover the bug fix or feature being
 112   added.
 113 - `make test` passes.
 114
 115 ### Code Coverage
 116
 117 [![Coverage Status](https://coveralls.io/repos/github/stacked-git/stgit/badge.svg?branch=master)](https://coveralls.io/github/stacked-git/stgit?branch=master)
 118
 119 We use [Coverage.py](https://coverage.readthedocs.io/en/coverage-5.5) to
 120 calculate code coverage on the repo. Run it with `make coverage`. There's a
 121 fancy GUI version tracking master at
 122 https://coveralls.io/github/stacked-git/stgit?branch=master.