Skip to content

Latest commit

 

History

History
106 lines (82 loc) · 5.56 KB

CONTRIBUTING.md

File metadata and controls

106 lines (82 loc) · 5.56 KB
Raw

Welcome to Goose contributing guide

Thank you for investing your time in contributing to our project!

Before you start contributing, we're presuming you've gone through all the architecture-decisions & had a discussion with the maintainers.

Request for feedback

We plan to release Goose 1.0.0 on February 1st, 2025, marking API stability and ensuring backward-compatibility, with no downtime during upgrades.

We welcome feedback from current and new users, especially if you’d like to request features or suggest changes to the API or implementation before the 1.0.0 release. Please share your thoughts via GitHub Issues or the Clojurians Slack.

Installation

Testing

The test suite is mostly integration tests, so use docker-compose to get the containerized Redis and RabbitMQ images for testing purposes.

$ docker-compose up -d                   # Sets up infra required for tests.
$ clj -X:test :nses '[goose.specs-test]' # Testing only 1 namespace.
$ clj -X:test                            # Running all tests.
$ docker-compose down                    # ...when you're done.

Formatting

  • Goose adheres to the weavejester/cljfmt library to maintain consistent code formatting.
  • Install the appropriate plugin for your IDE to ensure compliance.
$ clj -M:cljfmt fix                      # Automatically fix formatting issues.
$ clj -M:cljfmt check                    # Check any formatting inconsistencies.

Linting

$ clj-kondo --lint src                   # Linting src dir.
$ clj-kondo --lint test                  # Linting test dir.

Gotchas

  • Goose uses epoch in milliseconds

Coding Guidelines

These aren't exhaustive, but majorly inspired from The Clojure Style Guide

Documentation Guidelines

  • Every new feature should have an ADR, well-formatted docstrings & a Wiki Page.
  • ADRs (Architecture Decision Records) should be added to this folder.
  • Docstrings serve 3 purposes:
    1. Record the How and What of an external function
    2. Document usage of a function and meaning of its args
    3. Beautify documentation of Goose APIs on cljdoc, a documentation website for Clojure community
  • When writing docstrings, follow these guidelines:
    • Put code logic/reasoning in code-comments & only cover usage of a function in docstrings.
    • Format docstrings in markdown for parsing by Cljdoc.
    • Capitalize the first line.
    • Use double backslashes (\\) for line break when a new line isn't feasible.
    • Wrap positional args with backtick (example: :broker).
    • Link to other functions/data in Goose using API Wikilinks syntax (example: [[goose.retry/default-opts]]).
      • In API Wikilinks, use fully-qualified namespaces and avoid alias or relative paths for namespaces.

Making a Release

After feature-completion or bug-fix, we release a new version by marking a tag on Github, and publishing the new package to Clojars. Follow below steps when making a release:

  1. Compare code-changes between previous release and HEAD branch main by following this link.
  2. Choose a new release version based on semantic versioning guidelines.
  3. Commit new release version to README.md, CHANGELOG and pom.xml.
  4. Draft a new release by going to this link
  5. While choosing a tag, enter the release number to be created on publish.
  6. Click on Generate release notes, and review the generated notes.
  7. Click on Publish release, and track the status of new package publishing in CI.
  8. Verify Goose is released on Clojars and docs are updated on cljdoc.org.