view release on metacpan or  search on metacpan

CONTRIBUTING.md  view on Meta::CPAN

Testers database. The goal of this subproject is to be an
easily-consumable API so that users can build their own tools around
CPAN Testers data. This subproject is also a communication hub for the
disparate parts of the CPAN Testers data pipeline, and allows users to
tap into that communication to receive immediate data updates.

### Repository Layout

This project follows CPAN conventions with some additions, explained
below.

#### `lib/`

Modules are located in the `lib/` directory. Most of the functionality
of the project should be in a module. If the functionality should be
available to users from a script, the script should call the module.

##### `lib/CPAN/Testers/API.pm`

This is the main application class. This project uses [the Mojolicious
web framework](http://mojolicious.org). The main startup routines are
located in this file: reading the API spec (see below), locating the
template directory (see below), and setting up additional routes and
helpers.

##### `lib/CPAN/Testers/API/Controller/`

This is where API controllers are kept. Each controller handles
a section of the API, and API routes are linked from the API
specification in `share/api.json` (see below) to a controller name and
method using the `x-mojo-to` key in the API spec.

#### `bin/`

Command-line scripts go in the `bin/` directory. Most of the real
functionality of these should be in a library, but these scripts must
call the library function and document the command-line interface.

#### `t/`

All the tests are located in the `t/` directory. See "Getting Started"
below for how to build the project and run its tests.

#### `xt/`

Any extra tests that are not to be bundled with the CPAN module and run
by consumers is located here. These tests are run at release time and
may test things that are expensive or esoteric.

#### `share/`

Any files that are not runnable code but must still be available to the
code are stored in `share/`. This includes default config files, default
content, informational files, read-only databases, and other such. This
project uses [File::Share](http://metacpan.com/pod/File::Share) to
locate these files at run-time.

##### `share/api.json`

This is the [OpenAPI specification](http://openapis.org) for the CPAN
Testers API. This JSON document documents each API endpoint, the input
it can receive, the output it will send, and any error conditions that
might occur. This API documentation is then displayed [using
SwaggerUI](http://swagger.io/swagger-ui) (via
[Alien::SwaggerUI](http://metacpan.org/pod/Alien::SwaggerUI)) at
<http://api.cpantesters.org>.

Every new API endpoint must be started and documented here. This
document is used by
[Mojolicious::Plugin::OpenAPI](http://metacpan.org/pod/Mojolicious::Plugin::OpenAPI)
to generate the Mojolicious routes and validate the input and output
automatically. Each route should have an `x-mojo-to` key to link it to
a `controller` (class) and `action` (method). It should also have an
`operationId` that is globally unique for all API files.

##### `share/templates`

This is where Mojolicious templates should go. The templates are located
after install using [File::Share](http://metacpan.org/pod/File::Share).

##### `share/public`

This is where extra, ancillary files should go (like CSS, JavaScript,
and images). These files are located after install using
[File::Share](http://metacpan.org/pod/File::Share).

#### `Rexfile`

This file contains all the [Rex](http://rexify.org) tasks to deploy this
project to CPAN Testers servers (or development VMs). This `Rexfile`
coordinates with [the CPAN Testers deploy
project](http://github.com/cpan-testers/cpantesters-deploy) (which
prepares a machine for a specific role) to allow deploying the
application with minimal privileges.

#### `etc/`

This directory contains additional things that aren't examples (which
would go in `eg/`), but also must not be part of the CPAN distribution
(which would go in `share/`).

##### `etc/runit/`

These are [runit](smarden.org/runit/) service files used by CPAN Testers
to run the API daemon and the [Mercury](http://preaction.me/mercury)
daemon (a websocket message broker).

## What to Contribute

### Comments

The issue tracker is used for both bug reports and to-do list. Anything
on the issue tracker, open or closed, is available for discussion.

### Fixes

For fixes, simply fork and send a pull request. Fixes to anything,
documentation, code, tests, are equally welcome, appreciated, and
addressed!

If you are fixing a bug in the code, please add a regression test to
ensure it stays fixed in the future.

### Features

All contributions are welcome if they fit the scope of this project. If
you're not sure if your feature fits, open an issue and ask. If it doesn't
fit, we will try to find a way to enable you to add your feature in a