PREACTION / CPAN-Testers-Backend-0.005 / CONTRIBUTING.md

CONTRIBUTING

This project is free software for the express purpose of collaboration. We welcome all input, bug reports, feature requests, general comments, and patches.

Communication

If you're not sure about anything, please open an issue on Github issues and ask, or ask the CPAN Testers Discuss mailing list, or e-mail the project leader preaction@cpan.org or talk to us on IRC on irc.perl.org channel #cpantesters-discuss!

Standard of Conduct

To ensure a welcoming, safe, collaborative environment, this project will enforce a standard of conduct:

Unacceptable behavior will receive a single, public warning. Repeated unacceptable behavior will result in removal from the project.

Remember, all the people who contribute to this project are volunteers.

About this Project

The CPAN Testers project is an effort to ensure the stability and reliability of Perl and CPAN by running the test suites of uploaded CPAN distributions on various Perl versions, OSes, and hardware; collecting the results in a database; and alerting distribution authors when there is a test failure.

Project Goals

The CPAN Testers Backend handles all the data processing that turns the incoming test reports into useful information to be consumed by users of the API and web application. The goal of this subproject is to contain all the backend code and support routines needed to manage the CPAN Testers data (delegating to the CPAN::Testers::Schema as much as possible).

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.

Many of the modules in this project are executable modules using the Beam::Runner framework.

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 to locate these files at run-time.

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/container/

The files in this directory are Beam::Wire container files which are used to configure the various tasks that are available to run.

By adding this directory to the BEAM_PATH environment variable, the container files will be listed by the beam list command, making it easy to see what tasks are available.

etc/runit/

These are runit service files used to run processing daemons.

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 related project (if it means changes in this project).

When contributing a feature, please add some basic functionality tests to ensure the feature is working properly. These tests do not need to be comprehensive or paranoid, but must at least demonstrate that the feature is working as documented.

Getting Started Building and Running Tests

This project uses Dist::Zilla for its releases, but you aren't required to use it for contributing.

These instructions do require you have App::cpanminus (cpanm) installed. cpanm is a CPAN client to install Perl modules and programs. You can install cpanm by doing:

curl -L https://cpanmin.us | perl - App::cpanminus

Or, if you (not incorrectly) do not trust that, by using the existing cpan client that comes with Perl:

cpan App::cpanminus

You may need to be root or Administrator to install cpanminus.

This project also requires Perl version 5.24. If your Perl is not recent enough, you can install a new version of Perl in a local directory by using perlbrew (the easiest option) or plenv.

Using cpanm to install prereqs

The cpanm command is the easiest way to install this project's dependencies. In the root of the project, just run cpanm --installdeps . and the dependencies will be installed.

Using carton to install prereqs in an isolated directory

If you wish to isolate the prerequisites of this project so they do not interfere with other projects, you can use the Carton tool. Install Carton normally from CPAN using cpanm Carton, then use the carton command to install this module's prereqs in the local/ directory:

carton install

Once the prereqs are installed, you can use carton exec prove -lr t to run all the tests with the right prereqs. Putting carton exec in front of the command makes sure Perl uses the right library directories.

Using prove to run tests

Perl comes with a utility called prove which runs tests and gives a report on failures. To run the test suite with prove, do:

prove -lr t

This will run all the tests in the t directory, recursively, while adding the current lib/ directory to the library path.

You can run individual test files more quickly by passing them as arguments to prove:

prove -l t/my-test.t

Using Dist::Zilla to install prereqs and run tests

Once you have installed Dist::Zilla via cpanm Dist::Zilla, you can get this distributions's dependencies by doing:

dzil listdeps --author --missing | cpanm

Once all that is done, testing is as easy as:

dzil test

Before you Submit Your Contribution

All contributions are copyright their respective owners, so make sure you agree with the project license (found in the LICENSE file) before contributing.

The list of Contributors is calculated automatically from the Git commit log. If you do not wish to be listed as a contributor, or if you wish to be listed as a contributor with a different e-mail address, tell me so in the ticket or e-mail me at doug@preaction.me.

Code Formatting and Style

Please try to maintain the existing code formatting and style.

Documentation

Documentation is incredibly important, and contributions will not be accepted until documentated.

New Prerequisites

Though this project has a cpanfile, a Makefile.PL, and maybe even a Build.PL, these files are auto-generated and should not be edited. To add new prereqs, you must add them to the dist.ini file in the following sections:

If the section doesn't already exist, you can add it to the bottom of the dist.ini file.

The Recommends and TestRecommends will be automatically installed by Travis CI to test those parts of the code.

OS-specific prerequisites can be added using the Dist::Zilla::Plugin::OSPrereqs module.