Skip to content

Latest commit

 

History

History
74 lines (45 loc) · 5.12 KB

CONTRIBUTING.md

File metadata and controls

74 lines (45 loc) · 5.12 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 components. Athena makes use of the monorepo pattern, with each component 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

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

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. python - The programming language, 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. Mainly that most things can be done from the root of the repo; no need to cd to whatever component you're working on, and need to go through just.

For exploratory work, the suggested workflow is to have your code in the related component's entry point file. E.g. src/components/clock/src/athena-clock.cr for the clock component. 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 component, 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 components 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.