README.rst

Introduction

Thank the people who contribute to your Git/GitHub project by creating an AUTHORS file.

Installing authors

authors is available on GitHub at https://github.com/critical-path/authors.

If you do not have pip version 18.1 or higher, then run the following command from your shell.

[user@host ~]$ sudo pip install --upgrade pip

To install authors with test-related dependencies, run the following command from your shell.

[user@host ~]$ sudo pip install --editable git+https://github.com/critical-path/authors.git#egg=authors[test]

To install it without test-related dependencies, run the following command from your shell.

[user@host ~]$ sudo pip install git+https://github.com/critical-path/authors.git

(If necessary, replace pip with pip3.)

Using authors

First, select a project whose contributors you want to thank and change to its working directory (the directory in which the .git subdirectory resides).

[user@host ~]$ cd example-project

Then, run git with the log command and the --format option, redirecting standard output to authors.

[user@host example-project]$ git log --format=%an | authors

Finally, add and commit the newly-created AUTHORS file.

[user@host example-project]$ git add AUTHORS
[user@host example-project]$ git commit

Configuring authors

To configure authors, create a file named .authors.yml in your project's working directory. .authors.yml should be valid YAML and contain five key-value pairs.

authors recognizes the following five keys.

• name: The name of the output file generated by authors.
• kind: The format of the output file, where adoc, html, md, rst, and txt are valid values.
• heading: The heading string.
• opening: The opening string.
• closing: The closing string.

If authors cannot find .authors.yml, or if it detects any missing or invalid values, then it will use the following default values.

name: AUTHORS
kind: md
heading: Authors
opening: Thank you to all of our contributors.
closing: This project would not be possible without you.

Testing authors

To conduct testing, run the following commands from your shell.

[user@host authors]$ flake8 --count authors
[user@host authors]$ pytest --cov --cov-report=term-missing

If any of the tests fail due to a PermissionError, then run the following command from your shell.

[user@host authors]$ sudo $(which pytest) --cov --cov-report=term-missing

On a final note, if you edit any of the existing templates, then be sure to make the corresponding changes to the unit tests. Otherwise, they will fail.