11# Contributing
22
33Contribution to diff-lcs is encouraged: bug reports, feature requests, or code
4- contributions. There are a few DOs and DON'Ts that should be followed.
4+ contributions. New features should be proposed and discussed in an
5+ [ issue] [ issues ] .
56
6- ## DO
7+ Before contributing patches, please read the [ Licence ] ( ./LICENCE.md ) .
78
8- - Keep the coding style that already exists for any updated Ruby code (support
9- or otherwise). I use [ Standard Ruby] [ standardrb ] for linting and formatting.
9+ diff-lcs is governed under the [ Contributor Covenant Code of Conduct] [ cccoc ] .
1010
11- - Use thoughtfully-named topic branches for contributions. Rebase your commits
12- into logical chunks as necessary.
11+ ## Code Guidelines
1312
14- - Use [ quality commit messages ] [ qcm ] .
13+ I have several guidelines to contributing code through pull requests:
1514
16- - Add your name or GitHub handle to ` CONTRIBUTORS.md ` and a record in the
17- ` CHANGELOG.md ` as a separate commit from your main change. (Follow the style
18- in the ` CHANGELOG.md ` and provide a link to your PR.)
15+ - All code changes require tests. In most cases, this will be added or updated
16+ unit tests. I use [ RSpec] [ rspec ] .
1917
20- - Add or update tests as appropriate for your change. The test suite is written
21- in [ RSpec] [ rspec ] .
18+ - I use code formatters, static analysis tools, and linting to ensure consistent
19+ styles and formatting. There should be no warning output from test run
20+ processes. I use [ Standard Ruby] [ standardrb ] .
2221
23- - Add or update documentation as appropriate for your change. The documentation
24- is RDoc; diff-lcs does not use extensions that may be present in alternative
25- documentation generators.
22+ - Proposed changes should be on a thoughtfully-named topic branch and organized
23+ into logical commit chunks as appropriate.
2624
27- ## DO NOT
25+ - Use [ Conventional Commits] [ conventional ] with my
26+ [ conventions] ( #commit-conventions ) .
2827
29- - Modify ` VERSION ` in ` lib/diff/lcs/version.rb ` . When your patch is accepted and
30- a release is made, the version will be updated at that point.
28+ - Versions must not be updated in pull requests unless otherwise directed. This
29+ means that you must not:
3130
32- - Modify ` diff-lcs.gemspec ` ; it is a generated file. (You _ may_ use
33- ` rake gemspec ` to regenerate it if your change involves metadata related to
34- gem itself).
31+ - Modify ` VERSION ` in ` lib/diff/lcs/version.rb ` . When your patch is accepted
32+ and a release is made, the version will be updated at that point.
3533
36- - Modify the ` Gemfile ` .
34+ - Modify ` diff-lcs.gemspec ` ; it is a generated file. (You _ may_ use
35+ ` rake gemspec ` to regenerate it if your change involves metadata related to
36+ gem itself).
3737
38- ## LLM-Generated Contribution Policy
38+ - Modify the ` Gemfile ` .
3939
40- diff-lcs is a library with complex interactions and subtle decisions (some of
41- them possibly even wrong). It is extremely important that any issues or pull
42- requests be well understood by the submitter and that, especially for pull
43- requests, the developer can attest to the [ Developer Certificate of Origin] [ dco ]
44- for each pull request (see [ LICENCE] ( LICENCE.md ) ).
40+ - Documentation should be added or updated as appropriate for new or updated
41+ functionality. The documentation is RDoc; diff-lcs does not use extensions
42+ that may be present in alternative documentation generators.
43+
44+ - All GitHub Actions checks marked as required must pass before a pull request
45+ may be accepted and merged.
46+
47+ - Add your name or GitHub handle to ` CONTRIBUTORS.md ` and a record in the
48+ ` CHANGELOG.md ` as a separate commit from your main change. (Follow the style
49+ in the ` CHANGELOG.md ` and provide a link to your PR.)
4550
46- If LLM assistance is used in writing pull requests, this must be documented in
47- the commit message and pull request. If there is evidence of LLM assistance
48- without such declaration, the pull request ** will be declined** .
51+ - Include your DCO sign-off in each commit message (see [ LICENCE] ( LICENCE.md ) ).
4952
50- Any contribution (bug, feature request, or pull request) that uses unreviewed
51- LLM output will be rejected.
53+ ## AI Contribution Policy
54+
55+ diff-lcs is a library with complex interactions and subtle decisions (some of
56+ them possibly even wrong). It is extremely important that contributions of any
57+ sort be well understood by the submitter and that the developer can attest to
58+ the [ Developer Certificate of Origin] [ dco ] for each pull request (see
59+ [ LICENCE] ( LICENCE.md ) ).
60+
61+ Any contribution (bug, feature request, or pull request) that uses undeclared AI
62+ output will be rejected.
5263
5364## Test Dependencies
5465
@@ -58,28 +69,54 @@ tests in the same way that `rake spec` does.
5869
5970To assist with the installation of the development dependencies for diff-lcs, I
6071have provided a Gemfile pointing to the (generated) ` diff-lcs.gemspec ` file.
61- ` minitar.gemspec ` file. This will permit you to use ` bundle install ` to install
62- the dependencies.
72+ This will permit you to use ` bundle install ` to install the dependencies.
6373
6474You can run tests with code coverage analysis by running ` rake spec:coverage ` .
6575
66- ## Workflow
76+ ## Commit Conventions
77+
78+ diff-lcs has adopted a variation of the Conventional Commits format for commit
79+ messages. The following types are permitted:
80+
81+ | Type | Purpose |
82+ | ------- | ----------------------------------------------------- |
83+ | ` feat ` | A new feature |
84+ | ` fix ` | A bug fix |
85+ | ` chore ` | A code change that is neither a bug fix nor a feature |
86+ | ` docs ` | Documentation updates |
87+ | ` deps ` | Dependency updates, including GitHub Actions. |
88+
89+ I encourage the use of [ Tim Pope's] [ tpope-qcm ] or [ Chris Beam's] [ cbeams ]
90+ guidelines on the writing of commit messages
91+
92+ I require the use of [ git] [ trailers1 ] [ trailers] [ trailers2 ] for specific
93+ additional metadata and strongly encourage it for others. The conditionally
94+ required metadata trailers are:
95+
96+ - ` Breaking-Change ` : if the change is a breaking change. ** Do not** use the
97+ shorthand form (` feat!(scope) ` ) or ` BREAKING CHANGE ` .
98+
99+ - ` Signed-off-by ` : this is required for all developers except me, as outlined in
100+ the [ Licence] ( ./LICENCE.md#developer-certificate-of-origin ) .
67101
68- Here's the most direct way to get your work merged into the project:
102+ - ` Fixes ` or ` Resolves ` : If a change fixes one or more open [ issues] [ issues ] ,
103+ that issue must be included in the ` Fixes ` or ` Resolves ` trailer. Multiple
104+ issues should be listed comma separated in the same trailer:
105+ ` Fixes: #1, #5, #7 ` , but _ may_ appear in separate trailers. While both ` Fixes `
106+ and ` Resolves ` are synonyms, only _ one_ should be used in a given commit or
107+ pull request.
69108
70- - Fork the project.
71- - Clone your fork (` git clone git://github.com/<username>/diff-lcs.git ` ).
72- - Create a topic branch to contain your change
73- (` git checkout -b my_awesome_feature ` ).
74- - Hack away, add tests. Not necessarily in that order.
75- - Make sure everything still passes by running ` rake ` .
76- - If necessary, rebase your commits into logical chunks, without errors.
77- - Push the branch up (` git push origin my_awesome_feature ` ).
78- - Create a pull request against halostatue/diff-lcs and describe what your
79- change does and the why you think it should be merged.
109+ - ` Related to ` : If a change does not fix an issue, those issue references should
110+ be included in this trailer.
80111
112+ [ cbeams ] : https://cbea.ms/git-commit/
113+ [ cccoc ] : ./CODE_OF_CONDUCT.md
114+ [ conventional ] : https://www.conventionalcommits.org/en/v1.0.0/
81115[ dco ] : licences/dco.txt
82116[ hoe ] : https://github.com/seattlerb/hoe
83- [ qcm ] : http ://tbaggery .com/2008/04/19/a-note-about-git-commit-messages.html
117+ [ issues ] : https ://github .com/halostatue/diff-lcs/issues
84118[ rspec ] : http://rspec.info/documentation/
85119[ standardrb ] : https://github.com/standardrb/standard
120+ [ tpope-qcm ] : http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
121+ [ trailers1 ] : https://git-scm.com/docs/git-interpret-trailers
122+ [ trailers2 ] : https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---trailerlttokengtltvaluegt
0 commit comments