Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (65 loc) · 6.37 KB

CONTRIBUTING.md

File metadata and controls

100 lines (65 loc) · 6.37 KB

Contributing

First off, thank you for taking the time to contribute! Athena, and many other open source projects, would not be the same without you!

The following is intended to be a living document describing the guidelines for contributing to Athena, and its shards. Athena makes use of the monorepo pattern, with each shard having its own read only repository. As such, all contributions should directed towards this repository.

Start Here

Find something that isn't working as expected? Have an idea for a new feature/enhancement? Want to improve the documentation?

If you answer "Yes" to any of these, you've come to the right place! The first step is to search through the current issues and pull requests to see if it has already been reported and/or resolved. If your search comes up empty then feel free to create an issue, or if you're still not sure if you should make one, stop by the Discord server to ask just to be sure; even if the answer is most likely always going to be yes.

Issue Tracker

The issue tracker is the heart of the Athena. Use it for bugs, questions, proposals, and feature requests.

Please always open a new issue before sending a pull request if you want to add a new feature to Athena, unless it is a minor obvious fix, or is in relation to an already open & approved issue. This reduces the likelihood of wasted effort, and ensures the end result is robust by being able to work out implementation details before the work is started.

Local Development

Before staring any local development, be sure to fork the repo, then create a branch to use for the related approved issue you're working on.

Due to Athena's usage of a monorepo, the same single repo can be used to contribute code to all shards.

In addition to Crystal itself, Athena makes use of just as its command runner. just provides a simple way of executing common commands needed for development.

Once you have it installed, and have cloned the monorepo, first install all the shard dependencies by running:

just install

And that's it, you are now ready to start coding! From here there are some additional optional tools that will come in handy:

  1. typos - Source code spell checker, used as part of the spellcheck recipe.
  2. watchexec - Executes commands in response to file modifications, used as part of the watch and watch-spec recipes.
  3. kcov - Code coverage tool, used to generate coverage reports/files as part of the test recipes.
  4. changie - Changelog management tool, used as part of the change recipe.
  5. uv - Python package manager, used for the docs related recipes.

TIP: Running just will provide a summary of available recipes.

Development

Because of Athena's usage of a monorepo some interactions may be different than a normal shard. Most things can be done from the root of the repo; no need to cd to whatever shard you're working on; can just go through just.

For exploratory work, the suggested workflow is to have your code in the related shard's entry point file. E.g. src/components/clock/src/athena-clock.cr for the clock shard. From here you can run just watch clock and that will re-run the file when changes are made. This makes it simple to play around with early implementations before there is proper test coverage.

Testing

Similar to development itself, running the specs are also done through just: just test clock would run the spec suite for that shard, and generate coverage information if you have kcov installed. The watch-test recipe can come in handy to provide quicker feedback while the tests are under development.

Athena Spec

Many Athena shards make use of Athena Spec for their unit/integration tests. This library provides an alternate DSL that is 100% compatible with the standard library's Spec module. I.e. they can be used together seamlessly, using whatever DSL is more appropriate for what is being tested. Being familiar with the base ASPEC::TestCase type will not only make reading the specs easier, but writing them as well. It comes with various features to make the tests simpler, reusable, and extensible. You may even want to use it in your own projects 😉.

Linting

Beyond testing, Athena makes use of various forms of linting, including:

  • ameba for static code analysis
  • typos for spell checking
  • The Crystal formatter for code formatting

All of these can be executed at once via the just lint recipe, but may also be ran individual as needed via their related just recipe.

Documentation

Athena's documentation site may be built locally via the just build-docs recipe. Alternatively, a live-updating server may be started via the just serve-docs recipe.

Opening a PR

At this point the code on your branch should have a passing test suite, including linting/spellchecking, and updated documentation if applicable. From here the only step left is to open a PR.

NOTE: Once the PR is opened, please avoid force-pushing to that branch.

Athena comes with a PR template that should be filled out; being sure to reference the issue number in the context section. E.g. Resolves #xxx. The changelog section should include all changes, both internal and external being sure to highlight breaking changes by prefixing the line with **Breaking:**. Additionally, changes that affect end users should also have a changie change file. These can most easily be created by following along the prompts of just change. Project maintainers can add the file(s) themselves if needed to move things along; just being sure to give proper attribution in the change file.

NOTE: As of now you'll need to open the PR before creating the change file in order to know what the PR number is.