Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (82 loc) · 5.69 KB

CONTRIBUTING.md

File metadata and controls

102 lines (82 loc) · 5.69 KB
Raw

Contributing

Contributions from anyone are welcome, whether code, documentation, or ideas!

Code

Contributions should come in the form of a Pull Request. We try to keep the discussion of the change on the PR for visibility and context.

Documenting code

  • .kt files should have complete kdocs as defined here: Kotlin Documentation for Comments
  • Use the appropriate linking mechanisms when referencing other code constructs.
  • Use the appropriate syntax highlighting mechanism for constants like null or true, as well as literals like "this text", and wherever else it leads to better readability.
  • Rely on the type system when writing docs. Avoid phrases like "A class that...", "This String ...", etc. In most cases the content that immediately follows these phrases can stand alone. For example, "A class that hHolds the contents of a line of text." or "This String is tThe license key for the s.io SDK.".
  • Write in proper english: complete sentences, proper punctuation, correct capitalization, and correct spelling.
  • Comment your code liberally.
    • Focus on explaining why the code is the way it is.
    • Supplement the explanation of why with one of what the code is doing when it noticeably improves readability.

Code linting and cleanup before committing

The DetektExtensions project has a builtin kotlin linter called ktlint. Ktlint is designed to automatically format and cleanup kotlin files to properly follow kotlin coding conventions. It is recommended to run the ktlint at least once before making a major code change commit and/or a pull request.

Methods of running ktlint

  1. Via the Intellj IDE and the Gradle Menu:
    • Navigate to Detekt Extensions -> Tasks -> formatting and run the ktlintFormat task.
      • If this method fails and you cannot see the exact reason why, re-run ktlint via the terminal or cmd line.
  2. In the Intellj Terminal window or the CMD prompt.
    • Navigate to the root of your checked out DetektExtensions repository.
      • (typically called DetektExtensions).
    • Run the command: gradlew ktlintFormat.
      • running the ktlintFormat via the terminal or cmd line window typically gives a more verbose output in regard to linter failures.

Committing

Commits should be focused and free of side effects. The goal is to have each commit be isolated enough that reverting a commit is easily done without losing unrelated functionality. For example, it is common to rename something as part of adding new functionality. This should be 2 commits: the rename, and the new functionality. This way, if the new functionality needs to be reverted, the renames stay.

Another common case is fixing a bug. Typically we'd like to see 2 commits: the first with a new, failing, automated test that reproduces the bug, and the second with the fix and any additional tests. This way, reviewers are able to see that the root cause was identified.

Commit message format

This project uses Conventional Commits. All commits merged to main must follow this format:

<type>: <description>

Valid types:

Type When to use Effect on version
feat New user-facing feature Bumps minor version
fix Bug fix Bumps patch version
feat! / fix! Breaking change Bumps major version
chore Maintenance, refactoring, no behavior change No version bump
deps Dependency update (used automatically by Renovate) No version bump
docs Documentation only No version bump
ci CI/CD changes No version bump
test Test-only changes No version bump
refactor Code restructure without behavior change No version bump

Examples:

  • feat: add RequireSecuredAnnotation rule
  • fix: handle null receiver in EnforceStaticImport
  • deps: update detekt to 2.0.0-alpha.4
  • chore: remove unused import

This project uses rebase+merge — each individual commit lands verbatim on main. Write every commit in conventional commit format. Fixup commits (fixup! feat: ...) are exempt and are skipped by the CI check; squash them into their parent commit before the merge rebase.

A CI check validates all non-fixup commit messages automatically. PRs with non-conforming commits cannot be merged.

Pull request rules & process

Once the pull request is made, do not squash until the PR has been approved and is ready for merge. Fixup commits should be made as separate commits, not as amends or squashed. Separate commits make it easier for reviewers to understand the changes made. If possible, also avoid rebasing until after receiving approvals.

When the PR is approved, fixup commits get squashed and the PR is rebased onto the target branch. Merges are always fast-forward. The merged branch should be deleted at the time the PR is merged.

Merge commits are reserved for forward-merging release branches that have received patches.

Release Process

Releases are automated via release-please:

  1. Merge conventional commits to main
  2. release-please opens or updates a release PR (bumps version in gradle.properties)
  3. Maintainer reviews and merges the release PR
  4. release-please creates a semver tag and GitHub Release with auto-generated notes
  5. The publish workflow publishes the release to Maven Central
  6. A follow-up PR is automatically created to bump to the next SNAPSHOT version

Conversation

Please file issues for this extension under github issues.