Skip to content

Latest commit

 

History

History
101 lines (66 loc) · 7.42 KB

README.md

File metadata and controls

101 lines (66 loc) · 7.42 KB
Raw

@seantrane/github-label-presets

:octocat: GitHub Labels that are logical, colorful and sensible.

Build Status devDependencies Status semantic-release

npm latest version npm next version npm downloads per week npm total downloads

About

TL;DR: Want beautiful GitHub Labels like these? Want to have them unobtrusively synced with your repos? Want to persist them indefinitely? Want to maintain your own labels? If the answers have been yes, this is definitely not too long, please read on.

  1. Run; npm install -g github-label-sync
  2. Provide env-vars; GITHUB_ACCESS_TOKEN, GITHUB_NAME, REPO
  3. Run; github-label-sync -l 'https://git.io/fAe5i' ${GITHUB_NAME}/${REPO}

Details

The default GitHub Labels are, well... not ideal. This has been described many times:

There are many very good examples of GitHub Label strategies. Almost all of them are an improvement over the default. But for several reasons or another few, in practice, none of them have felt truly great or sustainable.

Principles

@seantrane/github-label-presets were designed according to the following thoughts and principles:

  • GitHub Labels are used for both Issues and Pull Requests (PR), therefore the label context should be agnostic.
  • An Issue/PR without labels should not require labels to solicit attention, therefore the default state should be label-less.
  • Issue/PR labels should only provide important context; priority, effort and the state of solution and/or decision-making.
  • "High Priority", sure, but "Low Priority" is a joke; go label-less instead.
  • Labels and their associated colors should have a logical connection that is intuitive at-a-glance.
  • Labels should be lowercase. It's easier to type and less competitive with Label-names.
  • Prefixes matter. Labels get chaotic without them. The chosen are;
    • effort = relative effort involved, fibonacci from 1 to 13
    • priority = designate immediacy; now, 2day or soon
    • state = describe decision; approved, blocked, inactive or pending
    • type = describe type; bug, chore, discussion, docs, feature, fix, security, testing
    • work = describe situation; chaotic, complex, complicated or obvious
  • The only labels without prefixes are; breaking, good first issue, greenkeeper, help and semantic-release

Label Groups

Standard Effort Priority State Type Work
Standard labels commonly used in most repositories. Describes the relative effort to complete an issue or pull request. Priority labels, but focused on describing the immediacy of attention required. Describes the decision state of the issue or pull request. Describes the type of issue or pull request. Describes the kind of work involved in resolving the issue, using the Cynefin framework.
Standard Labels Effort Labels Priority Labels State Labels Type Labels Work Labels

How It Works

  • github-label-sync is used to synchronize your GitHub labels with as few destructive operations as possible - similar labels get renamed.
  • The label config is loaded via path or URL, or more specifically; the config file supplied by @seantrane/github-label-presets.
  • The github-label-sync -l 'https://git.io/fAe5i' ${GITHUB_NAME}/${REPO} command is run to have the label config applied to your profile/repo.
  • The command can be run anywhere and anytime, but it's recommended during a CI plan. This will automatically keep your labels clean and synchronized with your chosen configuration - depending on how often your plan is run, of course.

Usage

Required: Generate a GitHub Access Token, provide it via GITHUB_ACCESS_TOKEN environment variable. If you cannot provide token as env-var, you may also pass it via CLI.

  1. Install npm install -g github-label-sync
  2. Dry-run github-label-sync -d -l 'https://git.io/fAe5i' <github_name>/<github_repo>
  3. Run github-label-sync -l 'https://git.io/fAe5i' <github_name>/<github_repo>
  4. optional: provide token via param; github-label-sync -a <github_token> -l ...

CI/CD

You can use your CI/CD process to automate the periodic syncing of your repository labels. This can help persist order automatically.

Travis CI

Make sure GITHUB_ACCESS_TOKEN env-var is available.

before_install: npm install -g github-label-sync
script: github-label-sync -d -l 'https://git.io/fAe5i' <github_name>/<github_repo>
deploy:
  provider: script
  script: github-label-sync -l 'https://git.io/fAe5i' <github_name>/<github_repo>

Config your own...

You can provide your own labels.json via the [ -l, --lables ] argument.

Contribute

Contributions are always appreciated. Read CONTRIBUTING.md documentation to learn more.

Changelog

Release details are documented in the CHANGELOG.md file, and on the GitHub Releases page.

License

ISC License

Copyright (c) 2018 Sean Trane Sciarrone