pengwynn / flint

Check your project for common sources of contributor friction.

Flint

Check your project for common sources of contributor friction.

For the Non-Developer

Flint checks if your project's folder contains the proper files and structure to allow potential contributors to understand: 1) the project's goals, 2) how to contribute, 3) usage guidelines, and 4) how to install the project.

Install

If you've got Go installed, you can install flint with Go's command line interface:

go get github.com/pengwynn/flint

If you don't have Go installed, you can download a prebuilt binary for your platform, optionally renaming it to "flint" for convenience.

If you are on macOS and are using Homebrew as package manager you can install flint with:

brew install flint-checker

You can test your installation by running flint --version from any folder.

Usage

Run flint from your project root to check for some common ways to improve the experience for potential contributors. Here's the output for a blank folder to show the full gamut of suggestions:

~/projects/dream
❯ flint
[ERROR] README not found
[INFO] Every project begins with a README. http://bit.ly/1dqUYQF
[ERROR] CONTRIBUTING guide not found
[INFO] Add a guide for potential contributors. http://git.io/z-TiGg
[ERROR] LICENSE not found
[INFO] Add a license to protect yourself and your users. http://choosealicense.com/
[WARNING] Bootstrap script not found
[INFO] A bootstrap script makes setup a snap. http://bit.ly/JZjVL6
[WARNING] Test script not found
[INFO] Make it easy to run the test suite regardless of project type. http://bit.ly/JZjVL6
[CRITICAL] Some critical problems found.

You can also run this in older projects which were created by lazy you, or by younger, less wise you.

If you want to check a remote GitHub repository, you can now do so without cloning:

❯ flint --github pengwynn/dotfiles
[ERROR] CONTRIBUTING guide not found
[INFO] Add a guide for potential contributors. http://git.io/z-TiGg
[WARNING] Test script not found
[INFO] Make it easy to run the test suite regardless of project type. http://bit.ly/JZjVL6
[CRITICAL] Some critical problems found.

Passing the -h flag will show full usage options:

❯ flint -h
NAME:
   flint - Check a project for common sources of contributor friction

USAGE:
   flint [global options] command [command options] [arguments...]

VERSION:
   0.0.4

COMMANDS:
   help, h      Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --skip-readme        skip check for README
   --skip-contributing  skip check for contributing guide
   --skip-license       skip check for license
   --skip-bootstrap     skip check for bootstrap script
   --skip-test-script   skip check for test script
   --skip-scripts       skip check for all scripts
   --no-color           skip coloring the terminal output
   --github, -g         GitHub repository as owner/repo
   --token, -t          GitHub API access token [$FLINT_TOKEN]
   --help, -h           show help
   --version, -v        print the version

Philosophy

If you want people to use and contribute to your project, you need to start by answering their most basic questions. Flint is a command line script that will check your project for common answers to these questions.

What is this?

Since it is so important, GitHub founder Tom Preston-Werner suggests you should write the README before you write a single line of code. A well crafted README includes:

• A description of problems your project solves.
• The philosophy behind your project.
• Basic usage and getting started instructions.
• A list of comparable projects that inspired yours or would be suitable alternatives.

How am I allowed to use it?

Providing the source to your project isn't enough. While you don't have to provide a license, doing so will make it clear to users and potential contributors how they can legally use your software and what happens to contributions they make. Choose A License can help you pick the right license for your project.

How do I contribute?

You'll want to tell folks about your development workflow so they'll know how to submit patches for bugfixes and new features. When you add CONTRIBUTING guidelines to your project, GitHub will make those available at the top of every new Pull Request screen.

How do I get up and running in development?

A bootstrap script is a thoughtful way to let new users (and future versions of yourself on new hardware) get up and running quickly. A good bootstrap script detects and installs all project dependencies. Don't make your less technical users learn devops. Make it as easy as running script/bootstrap.

How do I make sure my new features didn't break old functionality?

Good software projects have test suites that ensure the code works as advertised. Even within language communities, there can be a myriad of test frameworks. You can make it easy to run the test suite with a platform agnostic script/test executable.

Maintainers

@pengwynn

Copyright 2014 Wynn Netherland.

flint's Issues

Should recognize GNU's common COPYING file

GNU projects often use the file name COPYING instead of LICENSE. flint should IMHO recognize it and treat it as sufficient as license file.

Possible additional info/templates etc.

Not sure if this is the best place/way to add a suggestion, but I couldn't find any other obvious way. Feel free to point me at a discussion list or email address if this is the wrong place.

A long time ago I had an attempt at putting together advice and templates on documenting open source projects which is here;

http://minkirri.apana.org.au/~abo/projects/prjdocs/ProjectDocs.txt
http://minkirri.apana.org.au/~abo/projects/prjdocs/templates/

The templates are all in reStructuredText, not markdown, which has the advantage of being more readable as plaintext but would be easy to convert.

There are some bits I didn't quite polish up that well, and I think there are some bits missing (like "Design Decisions" documenting differences/similarities to other projects, libraries considered, design approaches taken/rejected etc).

I don't know if you'd find any of this useful, but feel free to copy/ignore/whatever.

Flint failed to find Readme.md

Would you be open to making flint case insensitive? https://github.com/pengwynn/flint/blame/master/flint/flint.go#L18-L22

CHANGELOG

ChangeLogs are a great way to communicate specific changes between versions without relying on having to read a commit log.

Maybe flint could check for the presence of a CHANGELOG file? Maybe fancier and more language specific would be checking the gemspec or package.json for a recent version, and making sure there's an entry in the ChangeLog for it?

Go vendoring?

flint-checker was just added as a new formula in Homebrew in Homebrew/homebrew-core#12701. The formula has six go_resource blocks.

Would you be willing to start using the Go vendor directory or one of the other Go vendor systems so that we can remove these resource blocks?

Atom Integration

I've created an Atom package that integrates with the Linter package to show issues. Though you might like to check it out. https://atom.io/packages/linter-flint

Code of conduct

Not to be snarky, but:

$ flint --github pengwynn/flint
[WARNING] CODE_OF_CONDUCT not found
[INFO] Let people know what to expect when they participate in the project

getopt error

$ flint
getopt: missing optstring argument
Try `getopt --help' for more information.
flint [OPTION...]
Checks a project for common sources of contributor friction
-r, --readme                                                  Check for existence of README
-c, --contributing                                            Check for contributing guidelines
-l, --license                                                 Check for a project license
-b, --bootstrap                                               Check for a bootstrap script
-t, --test                                                    Check for a test script
--no-readme                                                   Skip README check
--no-contributing                                             Skip contributing guide check
--no-license                                                  Skip license check
--no-bootstrap                                                Skip bootstrap script check
--no-test                                                     Skip test script check

github_fetcher arguments error

kruug@kruugdeb:~ $ go get github.com/pengwynn/flint

github.com/pengwynn/flint/flint

dev/go/src/github.com/pengwynn/flint/flint/github_fetcher.go:27: too many arguments in call to g.Client.Repositories
dev/go/src/github.com/pengwynn/flint/flint/github_fetcher.go:27: not enough arguments in call to g.Client.Repositories(url).One
kruug@kruugdeb:~ $ flint --version
-bash: flint: command not found

Not sure how to fix.

Optional color support

Perhaps using https://github.com/fatih/color

Installation instructions fail

~ > go get github.com/pengwynn/flint
package github.com/pengwynn/flint: cannot download, $GOPATH not set. For more details see: go help gopath
~ > echo $GOPATH
/Users/eno/gocode

Code of conduct

I know it's not universal, but it's an excellent sign of a healthy, welcoming project.

As an example: http://hapijs.com/help#Code%20of%20Conduct

Make checks DRY

I was browsing through Flint's source code and thought that there must be a better DRY-er way of implementing the checks. I thought I'd learn some Go and try DRY up the flint/flint.go file. Here is what I came up with:

func (l *Lint) Check(file, message, fixme string) {
    if !l.findFile(file) {
        l.Errors = append(l.Errors, &lintError{2, message})
        l.Errors = append(l.Errors, &lintError{0, fixme})
    }
}

func (l *Lint) CheckReadme() {
    l.Check(
        "README*",
        "[ERROR] README not found",
        "[FIXME] Every project begins with a README. http://bit.ly/1dqUYQF")
}

// etc.

=== RUN TestCheckReadme
--- PASS: TestCheckReadme (0.00 seconds)

I thought I'd ask you whether you'd merge a Pull Request before I actually made one. I think this is a good idea because I've ported Flint to Ruby some time ago (making Friction) and this is more or less the way I implemented it there.

Apologies for my Go code, I literally got started with it 3 hours ago. I've ran go fmt on it so it should be alright style-wise.

Ability to exclude directories

Tried out flint on my personal site for giggles, and it's matching files names in /assets and _posts folders. Would be awesome to be able to pass something like --exclude _posts --exclude=assets or similar.

Add installation instructions

How do I use this thing? :)

go module support

This tool is installable via brew. As go 1.17 comes out unless this project adds go module support it will not be installable and it may have to be removed from brew.

Would it be possible to migrate to using go modules

See Homebrew/homebrew-core#47627