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:** .. code-block:: xonsh $ACTIVITIES = ["authors"] And then run, .. code-block:: sh $ 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:** .. code-block:: 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:** .. code-block:: rever $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:** .. code-block:: markdown 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.