README

A checker for project owners to measure their open source project if it is a welcoming project for contributors or not.

Introduction
How To Install And Use
- Github Action
To Be Considered
WOSPM Metrics
Contributing
Code of Conduct

Introduction

wospm-checker is a commandline tool to measure how an open source project welcomes users and possible contributors. The tool checks the repository against a list of metrics. The metrics are mostly inspired by Github's Open Source Guides.

How To Install And Use

Install the package with composer.

composer global require wospm/checker

You can use --help parameter to how the options and other information of the command.

wospm-checker --help

WOSPM Checker version: 0.0.1
Options:
    --output            The format of output. JSON, READABLE (Default), NO, HTML.
    --verbose           Show the progress or not. (0 => No, 1 => Detailed,
                        2 => Dots)
    --no-colors         Disable the console colors. It is enabled by default.
    --strict            Enable strict mode. The script will have a higher
                        bound to give success code.
    --version           Show version.
    --help              Print this help.

You can check your project by running the wospm-checker command in the root folder of your repo.

/full/path/to/wospm-checker

Github Action

It is also ready on Github marketplace as an action with name "WOSPM Checker Github Action" to use in your pipeline.

To Be Considered

GitHub Rest API Rate Limit ❗❗❗

wospm-checker uses GitHub Rest API to fecth repository information in some of the metric checks. There some limits in using this API. When you use wospm-checker very frequently, you may hit the wall of anonymous limit of the API.

Client error: `GET https://api.github.com/repos/user/repo/labels` resulted in a `403 Forbidden` response:
{
  "message": "API rate limit exceeded for XX.XX.XX.XXX. (But here's the good news: Authenticated requests get a higher (truncated...)

You can use your personal access token to have a bigger rate limit. In order to do this, you need to create a YML file with name .wospm under the root folder of the repository to be checked.

github:
    auth_token: PERSONAL_ACCESS_TOKEN

WOSPM Metrics

WOSPM metrics are measures to make quantitative assessments about the open sourse projects if they are contributor friendly or not. They are not scientific values which are mostly derived from Open Source Guides.

Metric Rules

Every metric should check only one simple case
Metrics can be dependent to each other (If there is no README, no need to make any check in README content etc.)
Every metric should have a unique WOSPMXXX number and a unique title (uppercase and snake-case).

For more information about adding a new metric to the project, please Add New Metric section.

List of Existing Metrics

To see the details of the metrics, click the metric code for detailed document.

Code	Title	Description
WOSPM0001	USING_WOSPM	You are using WOSPM checker. It is a good start.
WOSPM0002	README	Every open source project should have a README file.
WOSPM0003	LICENSE	Every open source project should have a LICENSE file.
WOSPM0004	CONTRIBUTING	Every open source project should have a CONTRIBUTING file.
WOSPM0005	CODE_OF_CONDUCT	Every open source project should have a CODE_OF_CONDUCT file.
WOSPM0006	README_TOC	Every README file should have table of contents list.
WOSPM0007	LINK_TO_CONTRIBUTE	README should have a link to CONTRIBUTING file.
WOSPM0008	LINK_TO_CODE_OF_CONDUCT	README should have a link to CODE_OF_CONDUCT file.
WOSPM0009	README_ADEQUATE	README should have atleast 200 words.
WOSPM0010	INSTALLATION_SECTION	README file should have an installation section.
WOSPM0011	GITHUB_ISSUE_TEMPLATE	You should have issue templates on Github.
WOSPM0012	GITHUB_PR_TEMPLATE	You should have PR template on Github.
WOSPM0013	GITHUB_SHORT_DESCRIPTION	Project should have a short description on Github.
WOSPM0014	GITHUB_TOPICS	Related Github topics should be added to the repository.
WOSPM0015	GITHUB_LABELS	Project should have issue labels.
WOSPM0016	GITHUB_LABELS_USED	Labels should be used to highlight the issues.
WOSPM0017	GITHUB_CUSTOM_LABELS	Creating custom labels is a good practice.
WOSPM0018	GITHUB_LABELS_GFI_HW	good first issue and help wanted labels should exist.
WOSPM0019	GITHUB_CUSTOM_LABELS_USED	At least one custom label should be associated to an issue.
WOSPM0020	GITHUB_LABELS_GFI_HW_USED	good first issue and "help wanted" labels should be used.
WOSPM0021	GITHUB_RESPONSIVENESS	Responsive owners encourage users to be contributors.
WOSPM0022	GITHUB_CUSTOM_LABEL_DESCRIPTON	Custom labels should have descriptions.
WOSPM0023	NO_BROKEN_LINKS_IN_README	No broken links exists in README.
WOSPM0024	CONTRIBUTORS_SECTION	README file should have a contributors section.
WOSPM0025	CHANGELOG	Project should have a changelog published.

Badges

After the check, the checker will generate a overall status for the project. There types of status are considered;

Perfect: It means that the porject covers 100 percent of the metrics.
Welcoming: It means that the project covers atleast 90 percent of the metrics.
Not Ready: It means that the project is not ready to be accepted as Welcoming. The project covers between 50 and 90 percents of the metrics.
Bad: I means that the project is in very bad status. The coverage is under 50 percent.