From 6281f38b32d2db538033e949a714e9ce258d8977 Mon Sep 17 00:00:00 2001 From: Michael Miller Date: Wed, 1 Dec 2021 16:10:04 -0700 Subject: [PATCH] Add contributing guide --- CONTRIBUTING.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 2 files changed, 206 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0dbf778 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,204 @@ +# Contributing to Spectator + +Welcome to Spectator! We're glad you're here! + +Spectator strives to be an easy-to-use, batteries included testing framework for Crystal shards and applications. +The goal of Spectator is to: + +- Provide an easy-to-understand syntax for tests. Reading and writing tests should feel natural. +- Lower the bar to entry. Simplify non-trivial use cases make testing easier. +- Remove boilerplate. Reduce the amount of code necessary to get the job done. Provide common utilities. + +Spectator is heavily inspired by [RSpec](https://rspec.info/). +It tries to maintain compatibility with RSpec, but this isn't always possible. +Some language differences between [Ruby and Crystal](https://www.crystalforrubyists.com/) prohibit this. +Spectator also maintains feature parity with Crystal's [Spec](https://crystal-lang.org/reference/guides/testing.html). + +**Table of Contents** + +- [Useful links](#useful-links) +- [Repository hosting](#repository-hosting) +- [How can I contribute?](#how-can-i-contribute) + - [Upcoming](#upcoming) + - [How to submit changes](#how-to-submit-changes) + - [How to report a bug](#how-to-report-a-bug) + - [How to request an enhancement](#how-to-request-an-enhancement) + - [Where can I get help?](#where-can-i-get-help) +- [Development](#development) + - [Testing](#testing) + - [Style guide and conventions](#style-guide-and-conventions) + - [Branching](#branching) + +## Useful links + +Here are some useful links for Spectator: + +- [README](README.md) +- [Change log](CHANGELOG.md) +- [Architecture](ARCHITECTURE.md) +- Wiki [GitLab](https://gitlab.com/arctic-fox/spectator/-/wikis/home) | [GitHub](https://github.com/icy-arctic-fox/spectator/wiki) + - Big List of Matchers [GitLab](https://gitlab.com/arctic-fox/spectator/-/wikis/Big-List-of-Matchers) | [GitHub](https://github.com/icy-arctic-fox/spectator/wiki/Big-List-of-Matchers) +- [Documentation (Crystal docs)](https://arctic-fox.gitlab.io/spectator) +- Issue tracker [GitLab](https://gitlab.com/arctic-fox/spectator/-/issues) | [GitHub](https://github.com/icy-arctic-fox/spectator/issues) +- [Builds](https://gitlab.com/arctic-fox/spectator/-/pipelines) +- [Crystal Macros](https://crystal-lang.org/reference/syntax_and_semantics/macros/index.html) + - [API](https://crystal-lang.org/api/latest/Crystal/Macros.html) + +## Repository hosting + +Spectator is available on [GitHub](https://github.com/icy-arctic-fox/spectator) and [GitLab](https://gitlab.com/arctic-fox/spectator). +The primary housing for Spectator is [GitLab](https://gitlab.com/arctic-fox/spectator). +This is a preference of the primary developer ([arctic-fox](https://gitlab.com/arctic-fox)). +That doesn't mean GitLab is the only place to contribute! +The repository and wiki are mirrored and maintainers will ensure contributions get into the project. +Issues, pull requests, and other contributions are accepted on both. +Use whichever you prefer! + +## How can I contribute? + +You can contribute in a variety of ways. +One of the easiest ways to contribute is to use Spectator! +Provide us feedback and report and bugs or issues you find. +Being a testing framework, Spectator should be rock solid. + +If you want to contribute to the codebase, take a look at the open issues. +[GitLab](https://gitlab.com/arctic-fox/spectator/-/issues) | [GitHub](https://github.com/icy-arctic-fox/spectator/issues) +Any issue not assigned can be picked up. +Even if one is already assigned, you may still be able to help out, just ask! + +If there isn't an issue for something you want to add or change, please create one first. +That way, we can discuss it before possibly wasting time on a misunderstanding. +Check out the [upcoming](#upcoming) section for a list of upcoming changes. +Anyone submitting code to Spectator will get a call-out in the [change log](CHANGELOG.md). + +You can also help by writing tests or documentation for the wiki. + +### Upcoming + +These are the projects that Spectator maintainers are looking to tackle next. +These issues are quite substantial, but assistance would be greatly appreciated! + +- [Overhaul of the mock and stubbing system](https://gitlab.com/arctic-fox/spectator/-/issues/63) +- [Errors masked in DSL by `method_missing` (predicate matcher)](https://gitlab.com/arctic-fox/spectator/-/issues/64) +- [Custom matcher DSL](https://gitlab.com/arctic-fox/spectator/-/issues/65) +- [Compiler optimizations](https://gitlab.com/arctic-fox/spectator/-/issues/66) +- More tests! + +### How to submit changes + +Submit your changes as a pull request (either GitLab or GitHub). +Please keep change requests focused on a single feature or bug. +Larger pull requests may be broken up into logical pieces. +This helps reviewers digest the changes. + +Describe the purpose of the change, what it addresses. +Provide links to related issues, bugs the changes fix, or external resources (i.e. RSpec docs). +Note any significant items or breaking changes. +Include a snippet of code demonstrating the code, if applicable. + +Please include tests for new code and bug fixes. +Some parts of Spectator are harder to test than others. +Check out the [testing](#testing) section for more information. + +### How to report a bug + +Be sure you can reproduce the issue. +Try to reduce the amount of code and complexity needed to reproduce the issue. +Check of outstanding issues, it might already be reported. + +Open an issue (either [GitLab](https://gitlab.com/arctic-fox/spectator/-/issues/new) or [GitHub](https://github.com/icy-arctic-fox/spectator/issues/new)). +Provide information on what you're trying to do. +Include source code that reproduces the issue. +Add any specific details or specifics about your usage and environment. +For instance: using Windows, compiling with specific flags, dependencies on other shards, custom helper code, etc. + +Maintainers generally won't close an issue until they're certain it is resolved. +We may ask that you verify the fix on your end before closing the issue. + +### How to request an enhancement + +Check for existing feature requests, someone might already have the same idea. +Create a new issue (either [GitLab](https://gitlab.com/arctic-fox/spectator/-/issues/new) or [GitHub](https://github.com/icy-arctic-fox/spectator/issues/new)). +Explain what you're trying to do or would like improved. +Include reasoning - why do you want this feature, what would it help with? +Provide code snippets if it helps illustrate the idea. + +## Where can I get help? + +First checkout the [README](README.md) and wiki ([GitLab](https://gitlab.com/arctic-fox/spectator/-/wikis/home) | [GitHub](https://github.com/icy-arctic-fox/spectator/wiki)). +These two locations are official sources of information for the project. + +Look for existing issues before creating a new one. +We use issues for bugs, features, and general help/support. +You might find something that addresses your issue or points you in the right direction. +Adding a :+1: to the original issue is appreciated! + +If you can't find anything already out there, submit an issue. +Explain what you're trying to do and maybe an explanation of why. +Sometimes we might discover a better solution for what you're attempting to do. +Provide code snippets, command-line, and examples if possible. + +## Development + +Spectator is cross-platform and should work on any OS that [Crystal supports](https://crystal-lang.org/install/). +Development on Spectator is possible with a default Crystal installation (with Shards). + +To get started: + +1. Fork the repository [GitLab](https://gitlab.com/arctic-fox/spectator/fork/new) | [GitHub](https://github.com/icy-arctic-fox/spectator/fork) +2. Clone the forked git repository. +3. Run `shards` in the repository to pull developer dependencies. +4. Verify everything works by running `crystal spec`. + +At this point, dive into the code or check out the [architecture](ARCHITECTURE.md). + +### Testing + +Spectator uses itself for testing. +Please try to write tests for any new features that are added. +Bugs should have tests created for them to combat regression. + +The `spec/` directory contains all tests. +The feature tests are grouped into sub directories based on their type, they are: + +- `docs/` - Example snippets from Spectator's documentation. +- `features/` - Tests for Spectator's DSL and headline features. +- `issues/` - Tests for reported bugs. +- `matchers/` - Exhaustive testing of matchers. +- `rspec/` - Examples from RSpec's documentation modified slightly to work with Spectator. See: https://relishapp.com/rspec/ +- `spectator/` - Unit tests for Spectator internals. + +The `helpers/` directory contains utilities to aid tests. + +### Style guide and conventions + +General Crystal styling should be used. +To ensure everything is formatted correctly, run `crystal tool format` prior to committing. + +Additionally, [Ameba](https://crystal-ameba.github.io/) is used to encourage best coding practices. +To run Ameba, run `bin/ameba` in the root of the repository. +This requires that shards have been installed. + +Formatting checks and Ameba will be run as part of the CI pipeline. +Both are required to pass before a pull request will be accepted and merged. +Exceptions can be made for some Ameba issues. +Adding `#ameba:disable` to a line will [disable Ameba](https://crystal-ameba.github.io/ameba/#inline-disabling) for a particular issue. +However, please prefer to fix the issue instead of ignoring them. + +Please attempt to document every class and public method. +Documentation isn't required on private methods and trivial code. +Please add comments explaining algorithms and complex code. +DSL methods and macros should be heavily documented. +This helps developers using Spectator. + +HTML documentation is automatically generated (by `crystal docs`) and published to [GitLab pages](https://arctic-fox.gitlab.io/spectator). + +### Branching + +The `master` branch contains the latest stable code. +Branches are used for features, fixes, and release preparation. + +A new minor release is made whenever there is enough functionality to warrant one or some time has passed since the last one and there's pending fixes. +A new major release occurs when there are substantial changes to Spectator. +Known breaking changes are always in a major release. +Tags are made for each release. diff --git a/README.md b/README.md index 609ef81..188eacf 100644 --- a/README.md +++ b/README.md @@ -389,6 +389,8 @@ A mirror is maintained to [GitHub](https://github.com/icy-arctic-fox/spectator). Issues, pull requests (merge requests), and discussion are welcome on both. Maintainers will ensure your contributions make it in. +For more information, see: [CONTRIBUTING.md](CONTRIBUTING.md) + ### Testing Tests must be written for any new functionality.