a command-line utility for simplifying the contribution process of software projects
Contributing to open source projects requires a lot of process that many potential contributors are not familiar with.
Sorry - I don't use git. (video.js#781)
Perhaps another time; I'm not familiar with the testing framework and would have to get the whole environment set-up. (video.js#603)
Unfortunately I am not familiar with Github processes (video.js#734)
No, thanks. I'm too lazy to fork, download, build and run tests :) (video.js#673)
Hi. What is PR? :) (video.js#1247)
Not really sure how... (video.js#1297)
In all of these examples the person helped solve the issue, so it wasn't a lack of ability or willingness to help that blocked them, it was the requirement of knowing the tools and having the time to set up the project correctly.
The solution is easy -- everyone needs to agree to use the same programming language, version control, branching model, task runner, and testing framework. Since that's unlikely to happen, an alternative is to provide a common interface for contributors to interact with different projects.
This is what contrib is meant to be. With contrib a contributor can get set up and help out quickly, while also learning a project's specific tasks, version control commands, and other processes as they go.
$ contrib install twbs/bootstrap
$ contrib feature start
[write code]
$ contrib feature submit
With the previous commands, contrib will help you fork, clone, start a new branch, and submit your changes as a pull request. In many cases it will even run build scripts and automated tests. At the same time, contrib will show you the underlying git, github, and/or other tasks needed to perform the same steps manually. So you can either learn as you go or just speed through the process.
Note: By default, contrib works with any project on Github, using the most common contributor workflows. However, projects can create custom workflows, including projects not hosted on Github.
Contrib currently requires node.js and npm (a goal is to make it a stand-alone package)
Download and Install Node.js
Once Node.js is installed on your system you can install contrib as a command-line tool.
Note: If you get permissions errors on a unix/linux/mac system, add
sudobefore the command
npm install contrib --global
To download the source code of a project and set it up for contributions, use the contrib install command.
contrib install [PROJECT OR contrib.json URL]
# If on Github you can use the 'org/project' name
contrib install twbs/bootstrap
# If not on Github, use the URL of the project's contrib.json file
contrib install http://example.com/source/contrib.json
After you have the source code you will need to move into the source code direcotory.
cd [PROJECT DIR]
At the root of the project directory, run the contrib command. This will show you the available commands for the project and how to use them. While there's a suggested set of common commands, a project can completely customize which commands are available and what they do.
contrib
Commands are used like so
contrib [command] [options]
# For example
contrib foo --dry-run
| Flags | Description |
|---|---|
| -h, --help | Output usage information |
| -i, --interactive | Confirm each step before executing it |
| -d, --dry-run | Output all steps but do not execute them |
| -s, --step [step] | Specify a single step to execute |
| -b, --begin [step] | Specify a step to begin at |
| -e, --end [step] | Specify a step to stop after |
| -v, --version | Output the contrib version number |
Run contrib init to generate a contrib.json file with some suggested commands.
contrib init
Note: The quickest way to get started is probably to copy an existing contrib.json from another project that has a similar workflow, and then modify it for your needs.
The basic structure of a contrib.json file looks like this:
{
"meta": {
"name": "my-project",
"requirements": [
{
"name": "example requirement",
"home": "http://example.com"
}
]
},
"install": {
"desc": "Download and set up the project",
"steps": [
{ "exec": "echo First install step!", "desc": "Example first install step" },
{ "include": "setup" }
]
},
"setup": {
"desc": "Set up version control and install dependencies",
"steps": []
},
"update": {
"desc": "Get the latest copy of the code",
"steps": []
},
"test": {
"desc": "Run programmatic tests",
"steps": []
}
}
The meta object in the config file holds metadata for the project. The metadata can be used in commands.
{
"meta": {
"name": "my-project"
},
"say-name": {
"desc": "Echo the project name",
"steps": [
"echo The name of the project is {{ meta.name }}"
]
}
}
$ contrib say-name
-> The name of the project is my-project
Common meta object keys include:
contrib [command]
Any key of the main config object besides meta is considered a command. A command is defined with an object that has a description ("desc") and an array of steps. The description is displayed both when starting the command and in the help display. The steps array is a list of the command line scripts or built-in actions (e.g. prompt) that should be performed in order. The following example command would be run with contrib example, and would write out hello and then world.
{
"example": {
"desc": "Description of the example command",
"steps": [
"echo hello",
"echo world"
]
}
}
The previous command configuration can also be simplifed to just an array of the steps.
Note: this drops the description which can be very valuable for users even if the command seems obvious.
{
"example": [
"echo hello",
"echo world"
]
}
Finally for very simple command-to-task translations, a string can be used to define the command.
{
"test": "taskrunner test"
}
contrib [command] [subcommand]
Commands can also be set up to have subcommands. The following subcommands would be run with contrib feature start and contrib feature submit.
{
"feature": {
"desc": "Example command for creating a feature",
"start": {
"desc": "Start building a new feature",
"steps": [
"echo Starting Feature"
]
},
"submit": {
"desc": "Submit a finished feature",
"steps": [
"echo Submitting Feature"
]
}
}
}
Note: A subcommand must be defined using and object with a
stepskey. A string or array cannot be used like for top level commands.
Steps are the sequential actions that make up a command. A step can have an action, a description, and an ID.
{
"example": {
"desc": "Description of the example command",
"steps": [
{ "exec": "echo hello", "desc": "Write 'hello'", "id": "helloStep" },
{ "exec": "echo world", "desc": "Write 'world'", "id": "worldStep" }
]
}
}
Note: We define most steps in a single line to line-up the actions for easy reading, and to keep the length of the contrib.json from getting too long. This is different from typical json/javascript formatting, but can make a big difference with larger command sets.
If a step is defined as a string, it's assumed it's an "exec" action and the string is the command-line script/task to run.
{
"example": {
"desc": "Description of the example command",
"steps": [
"echo hello",
"echo world"
]
}
}
An alternative (but less obvious) method is to define the step as an array. In this case it's assumed the first item is the "exec" action, the second item is the description, and the third item is the ID. This format can help simplify commands that are long lists of exec actions with descriptions.
{
"example": {
"desc": "Description of the example command",
"steps": [
[ "echo hello", "Write 'hello'", "helloStep" ],
[ "echo world", "Write 'world'", "worldStep" ]
]
}
}
The description is shown for each step after the step number.
Note: It's best to provide a description for most steps so that project contributors can be learning the project's tools as they use contrib.
Here is how the description from the first step in the hello world example would look.
STEP 1. Write 'hello'
IDs can be used if you want to store the output or user-input of a step to be used in a later step. In this example we will get the current date in the first step and then use that in the second step.
{
"date": {
"desc": "Get and use the date",
"steps": [
{ "exec": "date +%Y:%m:%d", "id": "date" },
{ "exec": "echo The date in the first step was {{date}}" }
]
}
}
The second step should output something like The date in the first step was 2014:07:31.
Each step has a single action, defined as one of the following.
Run the given command-line script or task. If an ID is provided the trimmed output of the command will be saved as the ID.
{
"steps": [
{ "exec": "task/command-line script" }
]
}
Prompt steps ask the user for some type of information. The step description is the question to ask or a description of the information the user should enter. If you include an ID for the step the user's response can be used in a later step.
{
"steps": [
{ "prompt": "text", "desc": "What is your name?", "id": "name" },
{ "exec": "echo Your name is {{name}}" }
]
}
An open ended text input.
{
"steps": [
{ "prompt": "text", "desc": "What is your name?", "id": "name" }
]
}
Ask a question with a yes or no answer. A "no" response will immediately end the command and no other steps will be performed.
{
"steps": [
{ "prompt": "confirm", "desc": "Is this correct?" }
]
}
Include all steps from another command within the current command. In the following example, the contrib foo command will write out "hello" in Step 1 and then "world" in Step 2.
{
"foo": {
"steps": [
{ "exec": "echo hello" },
{ "include": "bar" }
]
},
"bar": {
"steps": [
{ "exec": "echo world" }
]
}
}
The specific contrib commands that are ultimately available in a project is completely up to the project owner. There's nothing stopping someone from creating completely custom commands and even using contrib outside of the open source project context. However when using with open source, the following commands (if included) should work as described.
When you run
contrib initit will create a contrib.json that includes these functions as described.
Copy/fork, download/clone, and set up the project. When install is run, contrib will load the given contrib.json and perform the install steps defined in it.
Set up version control and install dependencies. Set up is its own command and also included in the install command using the include step definition.
Get the latest changes to the code from the main project and update dependencies.
Run automated tests
In early projects using contrib you will see many of the following commands. They're based on common git + Github workflows so they may not work with projects that don't use those tools. And it's too early to say they're standard either way so feel free to experiment with and suggest different versions. The important thing is that you describe what your commands do so that when a contributor runs the contrib command they will be able to find what they're looking for.
Commands around writing code for the project.
If you're using the gitflow model you might have feature and hotfix commands. If you're using Github Flow you might just have feature commands. And if you're using subversion, mercurial or another version controls software, you might have something very different.
contrib feature start
contrib feature submit
contrib feature delete
Submit a bug report. This command can be useful for having contributors answer specific questions before submitting a report (especially with Github issues).
Submit a feature/enhancement request.
Submit a question. This command can help contributors discover where a project prefers they ask questions. It may be Stack Overflow, a forum, a mailing list, or somewhere else.
Build the program (if appropriate)
Start a local server for testing
Contrib is not meant to replace existing task runners or do everything a task runner can. It is meant to be a mapping of common processes to existing project-specific tasks and commands.
Contrib is meant to teach the underlying tasks and processes (not hide them) while also allowing the contributor to be immediately productive.
Copyright (c) 2014 heff. Licensed under the MIT license.
FAQs
a CLI for standarizing the contribution process across projects
The npm package contrib receives a total of 24 weekly downloads. As such, contrib popularity was classified as not popular.
We found that contrib demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.