forkability
forkability copied to clipboard
:fork_and_knife: A linter for your repository.
forkability
![Gitter](https://badges.gitter.im/Join Chat.svg)
Forkability helps you to make your project more open-source-friendly by pointing out missing features and useful tips.
How to use
Web App
https://basicallydan.github.io/forkability runs the code in its client-side form (works just fine). It allows you to log in using GitHub OAuth in order to get a higher API request quota.
Node Module/Command Line
npm install forkability -g
This will give you access to the forkability
CLI. This is how you use it:
forkability basicallydan/forkability
Or whatever your username/repo combo is. It'll work with any public repo. If you start getting angry messages that you've used up your GitHub request quota, use the --username
and --password
flags, like so:
forkability jashkenas/backbone --username myusername --password totallynotmypasswordloldonttryitplz
# Basic auth!
This will give you a pretty, colourful (if your terminal supports it), UTF-8-tastic (if your terminal supports it) list of features and suggested features, as well as a pretty badge you can include in your README or repo's web page. It looks a bit like this:
forkability basicallydan/interfake
# Forkability found 6 recommended features, and has 2 suggestions
# Features (6)
✓ Contributing document
✓ Readme document
✓ License document
✓ .gitignore file
✓ Test suite
✓ Tags are being used
---
# Suggestions (2)
! Changelog document
! Uncommented issue: Comment on the issue to indicate acknowledgement
└── Media Responses: https://github.com/basicallydan/interfake/issues/19
---
# Forkability Badge (failure)
## Just the SVG:
https://img.shields.io/badge/forkable-no-red.svg
## Markdown:
[![This repository's forkability could be improved](https://img.shields.io/badge/forkable-no-red.svg)](https://basicallydan.github.io/forkability/?u=basicallydan&r=interfake)
## HTML:
<a href="https://basicallydan.github.io/forkability/?u=basicallydan&r=interfake"><img alt="This repository's forkability could be improved" src="https://img.shields.io/badge/forkable-no-red.svg"></a>
Other Options
-
--reporter
(-r
): Specify how the lint report should be output (list
(default),json
orprettyjson
) -
--lang
(-l
): Specify languages to use for extra features to test. Comma-separated list. (available languages) -
--help
(-h
): How to use the module, and will list available languages
JavaScript API
If you're really, really into this jazz you can use the JS API. This is how it looks:
forkability(options, function(err, report) {
console.log('# Recommended files'.magenta);
report.passes.forEach(function(thing) {
console.log('✓'.green, thing);
});
report.failures.forEach(function(thing) {
console.log('✘'.red, thing);
});
});
options
accepts:
-
user
: The username of the repo owner (can be an organisation) -
repository
: The name of the repository -
fileDepth
: How deep to go into the file tree of the repo to check for files. (thanks @M-Zuber!) -
auth
: An object which can contain these thingies:-
username
: The username to authenticate with, using basic auth. -
password
: The password to authenticate with, using basic auth. Needs to be supplied withusername
. -
token
: If you're using OAuth or something, put the authentication token here. Check outpages/pages.js
to see this badassery in action!
-
Thankfully, that's it.
Badges
Thanks to the generosity of shields.io there is in fact a Forkability badge for your repo. It will be generated in all three APIs, but I'd recommend using the web app for quickest access to the badge code.
A note of caution: Although you can easily fake it, it'd be very much against the spirit of Forkability if you either used the pass badge when your repo currently isn't passing, or if you didn't link to the Forkability report. So: please don't do that :smile:
Contributing
Clone the repo using git clone [email protected]:basicallydan/forkability.git
or HTTPS if you'd prefer. Once it's downloaded, you can use make deps
to install dependencies. Use make help
to see other makefile
commands available such as test
, serve
and compile
which are all useful for developing and testing new features.
The default make
task will do the job of resolving dependencies, then testing the code, then compiling the code for the browser.
For more info on contributing to Forkability including guidelines, see contributing.md.
A key consideration when making contributions is to consider what makes a project forkable; there are many ways to look at a project and thus probably many opinions.
With this in mind we'd like to invite anybody reading this to open an issue, and/or make a pull request - pull requests are all the hotness right now - which details in some way what could be done to make this a more useful tool.
Contributors
Thanks to everybody who has helped. So far this includes:
- @basicallydan
- @M-Zuber
- @JJ
- @kirang89
- @jonfinerty
- @hpoom
- @matiassingers
- @algernon
- @rowanmanning
- @ExcaliburZero
- @charlotteis
Long-term goals of this project
- Give people a recognisable score for the open-source-friendliness ("forkability") of their project
- Inform people about the open-source movement
- Educate people on the benefits of open-sourcing their code
- Tell people about how they can improve the "forkability" of their project
Tests
Clone this repo, run npm install
, then npm test
.
Possible domains for this project:
- forkability.org
- forkability.io
Disclaimer
You should not use forkability as the sole way to judge how forkable your project is. After all, it is not in any way intelligent, it is merely looking for the presence of certain features in your project in order to nudge you in the right direction.
Your best bet to make your project as forkable as possible is to ask your friends, or your friendly neighbourhood open-source community!