repostatus.org
A standard to easily communicate to humans and machines the development/support and usability status of software repositories/projects.
What It Is
Many people and organizations have publicly available code in varying states of usability, development (whether or not further development is planned), and support (whether bugfixes and user assistance will be given). With the increased popularity of code sharing sites such as GitHub, Gitorious, etc. it’s becoming even more common for new projects to be shared publicly from the time of the first commit, and for projects to continue being publicly accessible long after development and support have ceased. So far, there seem to be few if any methods for authors/maintainers to indicate the usability and development/support status of a project. At best, tagging and releases (even when using semver properly) only differentiate between code that the author deems to be production-ready versus pre-release (and even the definition of pre-release states vary widely). There is no accepted way of indicating the development or support status of a project, specifically whether or not further development is planned and whether support will be provided. Repostatus.org aims to fill this gap by providing an easy-to-use method of communicating the usability and development/support status of a project to both humans and machines.
This is accomplished by including a simple badge or URL in your project’s README file, or by including a link in a specially-named file inside your project. The badge is easily visible to humans, and machines can determine the project’s status by searching for a string matching a specific pattern in a set list of possible files. We define a list of possible project statuses which aim to encompass axes of both code completion and development/support status (future plans), in a simple and user-centric manner.
Project Statuses
- Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.
- WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
- Suspended – Initial development has started, but there has not yet been a stable, usable release; work has been stopped for the time being but the author(s) intend on resuming work.
- Abandoned – Initial development has started, but there has not yet been a stable, usable release; the project has been abandoned and the author(s) do not intend on continuing development.
- Active – The project has reached a stable, usable state and is being actively developed.
- Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.
- Unsupported – The project has reached a stable, usable state but the author(s) have ceased all work on it. A new maintainer may be desired.
- Moved - The project has been moved to a new location, and the version at that location should be considered authoritative. This status should be accompanied by a new URL.
These status descriptions and the URLs to the corresponding icons are also available in a JSON file or in a more formal ontology using SKOS, defined in a JSON-LD file.
What It Looks Like
When using the recommended method (a badge embedded in your project’s README file), it’s as concise as this one image:
This incorporates three components:
- The image URL, which serves as the machine-readable status identifier. It points to a status-specific image hosted on repostatus.org, and also incorporates a specification version number.
- Alt-text on the image (this can generally be viewed in a browser by mousing over the image) which begins with the canonical project status (“Project Status:
") and can optionally be followed by a human-readable description of the status, provided by the project's maintainer(s). Such text might also be useful to appear after the badge. - The image is linked back to the particular status description on repostatus.org.
How to Use It
Setting up your project to use RepoStatus.org is as simple as adding the appropriate badge to your project’s README file. We define this file as any file at the top level of the project, whose name begin with the (case-insensitive) string ‘readme’. When programs check the project status, they will search through any /^readme.*$/i files in lexicographical order, and choose the first one with a valid repostatus.org status URL in it. If this isn’t suitable for your project, there are also some additional options described below (“Machine-Readable Only”). Note that while I’ve tried to think of this to be as flexible as possible, it’s very strongly suggested that the badge appear in a README file rendered on your project’s site (such as the readme rendering in GitHub repositories).
Below are the various status icons, along with paste-able markup to add them in a variety of markup languages. Feel free to alter the alt-text (after the first -) to suit your needs.
- Concept
markdown ReST HTML - WIP
markdown ReST HTML - Suspended
markdown ReST HTML - Abandoned
markdown ReST HTML - Active markdown ReST HTML
- Inactive
markdown ReST HTML - Unsupported
markdown ReST HTML - Moved
markdown ReST HTML - Note that there are special requirements around the formatting of this status. In the examples, replace http://example.comwith the project’s new URL. See Moved Identifier String, below, for more information.
Machine-Readable Only
If for some reason you don’t want people to see the repostatus.org status identifier (which defeats half the purpose of this idea, but may be valid for some people), you can place just the URL to the status image in a .repostatus.org or repostatus.org file in the top-level of your project. Per the specification, programs that determine project status check these files after the README file(s).
Specification
I really wanted to write a full specification for this, complete with versioned URLs and JSON metadata describing the different statuses. If anyone else in the world wants to use this stuff, maybe I’ll do that. In the mean time, here’s the current version of the “specification”.
For use of the repostatus.org vocabulary in a linked open data context, consult the JSON-LD file.
Identifier Strings
The repostatus.org badge URL is the authoritative identifier of status. Regardless of any other formatting, when machines attempt to determine status they should only key off of a URL matching /^http[s]?:\/\/.*repostatus\.org\/badges\/(.+)\/(.+)\.svg$/. The first capture group identifies the specification/API version, and the second identifies the status name. Note that the specification/API version can currently be a semver-compliant string, or the string “latest”.
Moved Identifier String
The “Moved” status is slightly more complicated as it must also specify the new location. Guidelines for use are as follows:
- If the link is embedded in a markup format that supports alt-text for images (i.e. ReST, Markdown or HTML), the alt-text must begin with the string “Project Status: Moved to
" where `` `` is the new URL (where the project was moved to). That string __should__ be followed by a hyphen and then the official status description. The image __must__ remain linked to the appropriate repostatus.org URL. The image markup __may__ be followed by a separate link to the new URL. - Markup formats not supporting alt-text for images (i.e. plaintext files) must specify this status in the format “
to ". - If no new URL exists yet, the repository should have the “Abandoned” status instead of “Moved”.
Any machine parsing of the “Moved” status should recursively follow repostatus.org identifiers to determine the final location of the project.
Machine Location and Parsing
Machine parsing is quite simple: first, search through any files in the top-level directory of the project (ideally on the default branch, usually master for git) matching /^readme.*$/i (note the case-insensitivity) in lexicographic order. The first one with a match for the identifier string (URL) wins, and the first complete match within the file wins. If no files match, then search for a .repostatus.org file, and if none is found, a repostatus.org file. Machine parsing should follow the full specification rather than assuming file names (or assuming that a project’s readme will be correctly displayed on GitHub).
There are some example parsers listed on the parsers page.
Changelog
See the CHANGELOG.md on GitHub.
Contributing
This is a crazy idea of mine. But I think it’s useful. I’m very open to comments, criticisms, suggestions, etc. Feel free to open an issue on GitHub or submit a pull request. Instructions for contributing are available in the README on GitHub. A list of contributors is also available.
Community Involvement
This project seems to have gained a lot more interest than I thought it would. As of April, 2017 there are over 1,200 references on GitHub to repostatus.org badge URLs. I do not want to be the sole person making decisions for this project. I encourage everyone who finds it useful to watch the repo on GitHub and provide their feedback in discussions, especially the issues with the discussion or “needs decision” labels. I’m handling the code updates, but I very much want this project to be driven based on consensus of those who use it.