Contributing¶ ↑

Contribution to diff-lcs is encouraged: bug reports, feature requests, or code contributions. New features should be proposed and discussed in an issue.

Before contributing patches, please read the Licence.

diff-lcs is governed under the Contributor Covenant Code of Conduct.

Code Guidelines¶ ↑

I have several guidelines to contributing code through pull requests:

• All code changes require tests. In most cases, this will be added or updated unit tests. I use Minitest.

• There are integration tests with RSpec which must not be broken, accessible through rake integration. This requires a non-bundled RSpec, gem install rspec.

• I use code formatters, static analysis tools, and linting to ensure consistent styles and formatting. There should be no warning output from test run processes. I use Standard Ruby.

• Proposed changes should be on a thoughtfully-named topic branch and organized into logical commit chunks as appropriate.

• Use Conventional Commits with my conventions.

• Versions must not be updated in pull requests unless otherwise directed. This means that you must not:

• Modify VERSION in lib/diff/lcs/version.rb. When your patch is accepted and a release is made, the version will be updated at that point.

• Modify diff-lcs.gemspec; it is a generated file. (You may use rake gemspec to regenerate it if your change involves metadata related to gem itself).

• Modify the Gemfile.

• Documentation should be added or updated as appropriate for new or updated functionality. The documentation is RDoc; diff-lcs does not use extensions that may be present in alternative documentation generators.

• All GitHub Actions checks marked as required must pass before a pull request may be accepted and merged.

• Add your name or GitHub handle to CONTRIBUTORS.md and a record in the CHANGELOG.md as a separate commit from your main change. (Follow the style in the CHANGELOG.md and provide a link to your PR.)

• Include your DCO sign-off in each commit message (see LICENCE).

AI Contribution Policy¶ ↑

diff-lcs is a library with complex interactions and subtle decisions (some of them possibly even wrong). It is extremely important that contributions of any sort be well understood by the submitter and that the developer can attest to the Developer Certificate of Origin for each pull request (see LICENCE).

Any contribution (bug, feature request, or pull request) that uses undeclared AI output will be rejected.

Test Dependencies¶ ↑

diff-lcs uses Ryan Davis’s [Hoe] to manage the release process, and it adds a number of rake tasks. You will mostly be interested in rake, which runs tests in the same way that rake spec does.

To assist with the installation of the development dependencies for diff-lcs, I have provided a Gemfile pointing to the (generated) diff-lcs.gemspec file. This will permit you to use bundle install to install the dependencies.

You can run tests with code coverage analysis by running rake spec:coverage.

Commit Conventions¶ ↑

diff-lcs has adopted a variation of the Conventional Commits format for commit messages. The following types are permitted:

I encourage the use of Tim Pope’s or Chris Beam’s guidelines on the writing of commit messages

I require the use of git trailers for specific additional metadata and strongly encourage it for others. The conditionally required metadata trailers are:

• Breaking-Change: if the change is a breaking change. Do not use the shorthand form (feat!(scope)) or BREAKING CHANGE.

• Signed-off-by: this is required for all developers except me, as outlined in the Licence.

• Fixes or Resolves: If a change fixes one or more open issues, that issue must be included in the Fixes or Resolves trailer. Multiple issues should be listed comma separated in the same trailer: Fixes: #1, #5, #7, but may appear in separate trailers. While both Fixes and Resolves are synonyms, only one should be used in a given commit or pull request.

• Related to: If a change does not fix an issue, those issue references should be included in this trailer.