Skip to content

Commit

Permalink
Merge pull request #1145 from non/topic/doc-overhaul-wip
Browse files Browse the repository at this point in the history
Topic/doc overhaul wip
  • Loading branch information
ceedubs authored Jun 27, 2016
2 parents 89bc41f + db8223c commit 3402608
Show file tree
Hide file tree
Showing 5 changed files with 175 additions and 176 deletions.
105 changes: 77 additions & 28 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,16 @@ layout: default
title: "Contributing"
section: "contributing"
---

# Contributor guide

Discussion around Cats is currently happening in the
[Gitter channel](https://gitter.im/typelevel/cats) as well as on Github
issue and PR pages. You can get an overview of who is working on what
via [Waffle.io](https://waffle.io/typelevel/cats).
## About this document

Feel free to open an issue if you notice a bug, have an idea for a
feature, or have a question about the code. Pull requests are also
gladly accepted.
This guide is for people who would like to be involved in building Cats.

People are expected to follow the
[Typelevel Code of Conduct](http://typelevel.org/conduct.html) when
discussing Cats on the Github page, Gitter channel, or other
venues.

We hope that our community will be respectful, helpful, and kind. If
you find yourself embroiled in a situation that becomes heated, or
that fails to live up to our expectations, you should disengage and
contact one of the [project maintainers](README.md#maintainers) in private. We
hope to avoid letting minor aggressions and misunderstandings escalate
into larger problems.

If you are being harassed, please contact one of [us](README.md#maintainers)
immediately so that we can support you.
This guide assumes that you have some experience doing Scala
development. If you get stuck on any of these steps, please feel free
to [ask for help](#getting-in-touch).

## How can I help?

Expand All @@ -45,11 +30,12 @@ skip these steps and jump straight to submitting a pull request.

1. [Find something that belongs in cats](#find-something-that-belongs-in-cats)
2. [Let us know you are working on it](#let-us-know-you-are-working-on-it)
3. [Implement your contribution](#write-code)
4. [Write tests](#write-tests)
5. [Write documentation](#write-documentation)
6. [Write examples](#write-examples)
7. [Submit pull request](#submit-a-pull-request)
3. [Build the project](#build-project)
4. [Implement your contribution](#write-code)
5. [Write tests](#write-tests)
6. [Write documentation](#write-documentation)
7. [Write examples](#write-examples)
8. [Submit pull request](#submit-a-pull-request)

### Find something that belongs in cats

Expand Down Expand Up @@ -100,6 +86,39 @@ there isn't already an issue and it is a non-trivial task, it's a good
idea to create one (and note that you're working on it). This prevents
contributors from duplicating effort.

### Build the project

First you'll need to checkout a local copy of the code base:

```sh
git clone [email protected]:typelevel/cats.git
```

To build Cats you should have
[sbt](http://www.scala-sbt.org/0.13/tutorial/Setup.html) and [Node.js](https://nodejs.org/)
installed. Run `sbt`, and then use any of the following commands:

* `compile`: compile the code
* `console`: launch a REPL
* `test`: run the tests
* `unidoc`: generate the documentation
* `scalastyle`: run the style-checker on the code
* `validate`: run tests, style-checker, and doc generation

#### Scala and Scala-js

Cats cross-compiles to both JVM and Javascript(JS). If you are not used to
working with cross-compiling builds, the first things that you will notice is that
builds:

* Will take longer: To build JVM only, just use the `catsJVM`, or `catsJS` for

JS only. And if you want the default project to be `catsJVM`, just copy the
file `scripts/sbtrc-JVM` to `.sbtrc` in the root directory.

* May run out of memory: We suggest you use
[Paul Philips's sbt script](https://github.com/paulp/sbt-extras) that will use the settings from Cats.

### Write code

TODO
Expand All @@ -126,7 +145,7 @@ with [Discipline](https://github.com/typelevel/discipline) for law checking, and
that the `Validated` data type supports.
- An exception to this is serializability tests, where the type class name is also included in the name.
For example, in the case of `Validated`, the serializability test would take the form,
*"Applicative[Validated[String, Int]"*, to indicate that this test is verifying that the `Applicative`
*"Applicative[Validated[String, Int]"*, to indicate that this test is verifying that the `Applicative`
type class instance for the `Validated` data type is serializable.
- This convention helps to ensure clear and easy to understand output, with minimal duplication in the output.
- It is also a goal that, for every combination of data type and supported type class instance:
Expand Down Expand Up @@ -199,7 +218,11 @@ issue number in the body of your pull request or commit message. For
example, if your pull request addresses issue number 52, please
include "fixes #52".

If you make changes after you have opened your pull request, please add them as separate commits and avoid squashing or rebasing. Squashing and rebasing can lead to a tidier git history, but they can also be a hassle if somebody else has done work based on your branch.
If you make changes after you have opened your pull request, please
add them as separate commits and avoid squashing or
rebasing. Squashing and rebasing can lead to a tidier git history, but
they can also be a hassle if somebody else has done work based on your
branch.

## How did we do?

Expand All @@ -215,3 +238,29 @@ over the project source code or lurking the
contributing. In fact, if you encounter any confusion or frustration
during the contribution process, please create a GitHub issue and
we'll do our best to improve the process.

## Getting in touch

Discussion around Cats is currently happening in the
[Gitter channel](https://gitter.im/typelevel/cats) as well as on Github
issue and PR pages. You can get an overview of who is working on what
via [Waffle.io](https://waffle.io/typelevel/cats).

Feel free to open an issue if you notice a bug, have an idea for a
feature, or have a question about the code. Pull requests are also
gladly accepted.

People are expected to follow the
[Typelevel Code of Conduct](http://typelevel.org/conduct.html) when
discussing Cats on the Github page, Gitter channel, or other
venues.

We hope that our community will be respectful, helpful, and kind. If
you find yourself embroiled in a situation that becomes heated, or
that fails to live up to our expectations, you should disengage and
contact one of the [project maintainers](README.md#maintainers) in private. We
hope to avoid letting minor aggressions and misunderstandings escalate
into larger problems.

If you are being harassed, please contact one of [us](README.md#maintainers)
immediately so that we can support you.
45 changes: 45 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Design

The goal is to provide a lightweight, modular, and extensible library
that is approachable and powerful. We will also provide useful
documentation and examples which are type-checked by the compiler to
ensure correctness.

Cats will be designed to use modern *best practices*:

* [simulacrum](https://github.com/mpilquist/simulacrum) for minimizing type class boilerplate
* [machinist](https://github.com/typelevel/machinist) for optimizing implicit operators
* [scalacheck](http://scalacheck.org) for property-based testing
* [discipline](https://github.com/typelevel/discipline) for encoding and testing laws
* [kind-projector](https://github.com/non/kind-projector) for type lambda syntax
* [algebra](https://github.com/non/algebra) for shared algebraic structures
* ...and of course a pure functional subset of the Scala language.

(We also plan to support [Miniboxing](http://scala-miniboxing.org) in a branch.)

Currently Cats is experimenting with providing laziness via a type
constructor (`Eval[_]`), rather than via ad-hoc by-name
parameters. This design may change if it ends up being impractical.

The goal is to make Cats as efficient as possible for both strict and
lazy evaluation. There are also issues around by-name parameters that
mean they are not well-suited to all situations where laziness is
desirable.

### Modules

Cats will be split into modules, both to keep the size of the
artifacts down and also to avoid unnecessarily tight coupling between
type classes and data types.

Initially Cats will support the following modules:

* `macros`: Macro definitions needed for `core` and other projects.
* `core`: Definitions for widely-used type classes and data types.
* `laws`: The encoded laws for type classes, exported to assist third-party testing.
* `cats-free`: Free structures such as the free monad, and supporting type classes.
* `tests`: Verifies the laws, and runs any other tests. Not published.

As the type class families grow, it's possible that additional modules
will be added as well. Modules which depend on other libraries
(e.g. Shapeless-based type class derivation) may be added as well.
5 changes: 5 additions & 0 deletions PROCESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,11 @@ the new version's tags.
(In the future we may want to create branches for major versions,
e.g. `v1.x`. For now we don't have these.)

The release will take a few hours to sync to
[Maven Central](http://search.maven.org/). It's usually better to hold
off announcing the release until this sync has happened. (Before the
sync, users may not be able to resolve the new version.)

### Post-release

After the release occurs, you will need to update the
Expand Down
Loading

0 comments on commit 3402608

Please sign in to comment.