Contributor & Authorship Tracking

Rever helps you keep up-to-date with who is contributing to your project. This is through the authors activity. To get started, just add authors to your activities and then run rever setup.

rever.xsh:

$ACTIVITIES = ["authors"]

And then run,

$ rever setup

The above generates a few files for us and can be applied even to an existing project. By default, the author setup creates:

  • AUTHORS, a plain-text listing of the authors

  • .authors.yml, a YAML file for storing an configuring contributor information

  • .mailmap, a git file for mapping names and emails to alternatives.

These filenames can be configured via the $AUTHORS_FILENAME, $AUTHORS_METADATA, and $AUTHORS_MAILMAP, environment variables in the rever.xsh file, as with other activities.

If you have a long running, project, you may need to seed the .authors.yml metadata file with some information that disambiguate your contributors before rever setup will complete successfully. Don’t worry! This is totally normal and rever will present best guesses for you to choose from in order to obtain a clean set of metadata.

Metadata Format

The metadata that is kept about authors is a mix of manually-supplied, optional information (such as GitHub usernames) and data that can be mined from version control (such as emails, number of commits, etc.). The YAML file is a list of mappings as follows:

authors.yaml:

# required fields
- name: Princess Buttercup
  email: buttercup@florin.gov

# optional fields
  github: bcup
  is_org: False
  aliases:
    - Buttercup
    - beecup
  alternate_emails:
    - b.cup@gmail.com

# autogenerated fields
  num_commits: 1000
  first_commit: '1987-09-25'
- name: Westley
  email: westley@gamil.com
  github: westley
  aliases:
    - Dread Pirate Roberts
  alternate_emails:
    - dpr@pirates.biz
- name: Florin
  email: help@florin.gov
  github: florin
  is_org: True

Feel free to edit this file as much as you want, especially for aliases and alternate_email. It is the source of all downstream information. The rever setup command will generate a minimal version of this file that contains names and emails. Every release, the num_commits and first_commit fields will be recomputed and the metadata will be written back out.

AUTHORS File

The authors file is generated from the metadata and the following environment variables:

  • $AUTHORS_TEMPLATE: string that dictated how the authors file looks. It has the format keys sorting_text and authors

  • $AUTHORS_FORMAT: string the dictates how each author is formatted in the file. The fields of this string are the same as for the metadata.

  • $AUTHORS_SORTBY: string flag that specifies how authors should be sorted in the authors file. Valid options are:

    • "num_commits": Number of commits per author

    • "first_commit": Sort by first commit.

    • "alpha": Alphabetically.

So for example, the following configuration,

rever.xsh:

$PROJECT = "acme"
$ACTIVITIES = ["authors"]

$AUTHORS_FILENAME = "AUTHORS.md"
$AUTHORS_TEMPLATE = """
The $PROJECT project has some great contributors! They are:

{authors}

These have been sorted {sorting_text}.
"""
$AUTHORS_FORMAT= "* [{name}](https://github.com/{github})\n"
$AUTHORS_SORTBY = "alpha"

And say that Alice and Bob are our contributors, then we would generate:

AUTHORS.md:

The acme project has some great contributors! They are:

* [Alice](https://github.com/al1ce)
* [Bob](https://github.com/b0b)

These have been sorted alphabetically.

Latest Contributors

Additionally, the authors activity will generate a file that stores the (sorted) emails of all of the contributors since the last tag. This file is usually at $REVER_DIR/LATEST-AUTHORS.json, but may be configured by $AUTHORS_LATEST. This allows other activities (such as changelog) to access the list of all contributors for a particular version. Since this operates from the last tag, it is important to run the authors activity before the tag activity.