diff --git a/.github/labels/labels.json b/.github/labels/labels.json new file mode 100644 index 0000000000..24e94ab5b7 --- /dev/null +++ b/.github/labels/labels.json @@ -0,0 +1,339 @@ +[ + { + "name": "f00: breaking", + "color": "ffa6ff", + "description": "Introduces a breaking change needed to address issue.", + "aliases": [ + "s00: Breaking solution needed to address issue.", + "breaking", + "breaking change", + "breaking-change", + "Type: Breaking Change", + "type: breaking" + ] + }, + { + "name": "f01: semantic-release", + "color": "b75fff", + "description": "Introduces a change requiring semantic-release update (i.e. new UDI) to address issue.", + "aliases": [ + "s01: semantic-release requiring new UDI version", + "semantic-release" + ] + }, + { + "name": "e01", + "color": "91ca55", + "description": "Small effort", + "aliases": [ + "effort: 1" + ] + }, + { + "name": "e02", + "color": "c2e2a2", + "description": "Effort", + "aliases": [ + "effort: 2" + ] + }, + { + "name": "e03", + "color": "e9f4dc", + "description": "Medium effort", + "aliases": [ + "effort: 3" + ] + }, + { + "name": "e05", + "color": "fef6d7", + "description": "Large effort", + "aliases": [ + "effort: 5" + ] + }, + { + "name": "e08", + "color": "fef2c0", + "description": "Very Large effort", + "aliases": [ + "effort: 8" + ] + }, + { + "name": "e13", + "color": "fbca04", + "description": "Should probably be broken into smaller tasks", + "aliases": [ + "oldeffort: 13" + ] + }, + { + "name": "p00: critical :fire:", + "color": "ff0000", + "aliases": [ + "p00: critical", + "priority: critical", + "priority: now", + "Priority: Critical" + ] + }, + { + "name": "p01: soon", + "color": "db0000", + "aliases": [ + "priority: soon", + "priority: medium", + "Priority: Medium" + ] + }, + { + "name": "p02: next", + "color": "b80000", + "aliases": [ + "priority: next", + "priority: 2day", + "priority: high", + "Priority: High" + ] + }, + { + "name": "p03: low", + "description": "Minimal business benefit identified", + "color": "960000", + "aliases": [ + "priority: low" + ] + }, + { + "name": "p04: help", + "description": "Help is requested to determine how to prioritize", + "color": "760000", + "aliases": [ + "help", + "help wanted", + "Patch Welcome", + "status: help wanted", + "Status: PR Welcome", + "Status: Ready for PR" + ] + }, + { + "name": "s00: approved", + "color": "00cb5e", + "description": "Approved to proceed.", + "aliases": [ + "state: approved", + "approved" + ] + }, + { + "name": "s01: blocked :no_entry:", + "color": "00ff8c", + "description": "Something is blocking action.", + "aliases": [ + "s01: blocked :no entry:", + "s01: blocked", + "state: blocked", + "blocked", + "Status: Blocked", + "status: blocked" + ] + }, + { + "name": "s02: pending", + "color": "009931", + "description": "A feature that needs dependencies merged, or a bug that needs further data.", + "aliases": [ + "state: pending", + "in progress", + "on hold", + "pending", + "Status: In Progress", + "Status: Review Needed", + "watchlist" + ] + }, + { + "name": "s03: inactive", + "color": "003c00", + "description": "The issue is either fixed, addressed better by other issues, or just out of product scope.", + "aliases": [ + "state: inactive", + "duplicate", + "invalid", + "stale", + "Status: Abandoned", + "status: duplicate", + "status: wontfix", + "wont-fix", + "wontfix" + ] + }, + { + "name": "t00: bug :bug:", + "color": "ff9800", + "description": "Something isn't working.", + "aliases": [ + "t00: bug", + "type: bug", + "bug", + "Type: Bug" + ] + }, + { + "name": "t01: security :key:", + "color": "d17200", + "description": "Something is vulnerable or not secure.", + "aliases": [ + "type: security", + "security" + ] + }, + { + "name": "t02: fix :hammer_and_wrench:", + "color": "a44f00", + "description": "Iterations on existing features or infrastructure.", + "aliases": [ + "t02: fix :hammer & wrench:", + "t02: fix", + "fix", + "improvement", + "optimization", + "refactor", + "Type: Fix", + "Type: Refactoring" + ] + }, + { + "name": "t03: testing :lab_coat:", + "color": "7b2c00", + "description": "Related to testing.", + "aliases": [ + "t03: testing :lab coat:", + "t03: testing", + "type: testing", + "test", + "testing" + ] + }, + { + "name": "t04: feature", + "color": "570400", + "description": "Brand new functionality, features, pages, workflows, endpoints, etc.", + "aliases": [ + "type: feature", + "addition", + "enhancement", + "feature", + "type: enhancement", + "Type: Feature" + ] + }, + { + "name": "t05: chore", + "color": "520000", + "description": "Other necessary (but less impactful) tasks.", + "aliases": [ + "type: chore", + "chore", + "dependabot", + "dependencies", + "dependency", + "greenkeeper", + "legal", + "maintenance", + "Type: Maintenance", + "type: maintenance" + ] + }, + { + "name": "t06: docs :book:", + "color": "623f1b", + "description": "Related to documentation and information.", + "aliases": [ + "t05: docs", + "type: docs", + "doc", + "docs", + "document", + "documentation", + "documents", + "Type: Documentation", + "type: documentation" + ] + }, + { + "name": "t07: discussion", + "color": "524438", + "description": "Questions, proposals and info that requires discussion.", + "aliases": [ + "type: discussion", + "discussion", + "feedback", + "help wanted", + "idea", + "Idea", + "Proposal", + "proposal", + "question", + "type: design", + "Type: Question", + "type: question" + ] + }, + { + "name": "w04: chaotic", + "color": "5785ff", + "description": "The situation is chaotic, novel practices expected to be used.", + "aliases": [ + "work: chaotic", + "chaotic" + ] + }, + { + "name": "w03: complex", + "color": "2768dd", + "description": "The situation is complex, emergent practices expected to be used.", + "aliases": [ + "work: complex", + "complex" + ] + }, + { + "name": "w02: complicated", + "color": "004dbc", + "description": "The situation is complicated, good practices expected to be used.", + "aliases": [ + "work: complicated", + "complicated" + ] + }, + { + "name": "w01: statndard", + "color": "00349c", + "description": "The situation is obvious, best practices expected to be used.", + "aliases": [ + "work: obvious", + "obvious" + ] + }, + { + "name": "w05: good first issue", + "color": "7057ff", + "description": "Good for newcomers. Careful review expected.", + "aliases": [ + "work: good first issue", + "good first issue", + "beginner-friendly", + "beginner", + "good for beginner", + "Good for beginners", + "good-starter-issue", + "starter-issue", + "starter", + "status: good starter issue" + ] + } +] diff --git a/.github/labels/labels_setup.md b/.github/labels/labels_setup.md new file mode 100644 index 0000000000..50e70cfe8e --- /dev/null +++ b/.github/labels/labels_setup.md @@ -0,0 +1,20 @@ + + +# Rational + +https://seantrane.com/posts/logical-colorful-github-labels-18230/ + + +# Hints for running + +Need to get your github token to change labels +```bash +npm install -g github-label-sync + +GITHUB_ACCESS_TOKEN=ghp_aaaaaaaaaaaoaaaaaaaaaaaaaaaaaaaaaaaa +github-label-sync -a ghp_aaaaaaaaaaaoaaaaaaaaaaaaaaaaaaaaaaaa -l labels.json BRAINSia/BRAINSTools +``` + +# Helpful resources for setting colors and icons +https://github.com/ikatyang/emoji-cheat-sheet +https://mycolor.space/?hex=%23FF0000&sub=1 diff --git a/github/CONTRIBUTING.md b/github/CONTRIBUTING.md new file mode 100644 index 0000000000..124ae41352 --- /dev/null +++ b/github/CONTRIBUTING.md @@ -0,0 +1,255 @@ +Contributing to BRAINSTools +=================== + +This page documents how to develop for BRAINSTools using [Git]. + +**Note**: *Git is an extremely powerful version control tool that supports many +different "workflows" for indivudal development and collaboration. Here we +document procedures used by the BRAINSTools development community. In the interest of +simplicity and brevity we do not provide an explanation of why we use this +approach. Furthermore, this is not a Git tutorial. Please see our [GitHelp] +guide for third-party documentation.* + +Setup +----- + +Before you begin, perform initial setup: + +```sh + $ git clone git@github.com:BRAINSia/BRAINSTools.git +``` + + 4. Run the developer setup script [`SetupForDevelopment.sh`] to prepare your + BRAINSTools work tree and create Git command aliases used below: + +```sh + $ ./Utilities/SetupForDevelopment.sh +``` + +Note that BRAINSTools defines some useful Git aliases, such as `pullall` or `prepush`, +through the [`SetupGitAliases.sh`] script for general Git tasks in BRAINSTools. + +Only a few experienced contributors have push access. Having push access is +not necessary to contribute to BRAINSTools. + +You may visit the *Pro Git: Setup* resource in [GitHelp] for further +information on setting up your local Git environment. + +Workflow +-------- + +BRAINSTools development uses a strategy similar to ITK +[branchy workflow]() based on topic +branches. Our collaboration workflow consists of three main steps: + + 1. Local Development + * [Update](#update) + * [Create a Topic](#create-a-topic) + 2. Code Review + * [Share a Topic](#share-a-topic) + * [Revise a Topic](#revise-a-topic) + 3. Integrate Changes + * [Merge a Topic](#merge-a-topic) (requires [Github push access]) + * [Delete a Topic](#delete-a-topic) + +Update +------ + +Update your local `master` branch: + +```sh + $ git checkout master + $ git pullall +``` + +Create a Topic +-------------- + +All new work must be committed on topic branches. Name topics like you might +name functions: concise but precise. A reader should have a general idea of the +feature or fix to be developed given just the branch name. + +To start a new topic branch: + +```sh + $ git fetch origin +``` + +For new development, start the topic from `origin/master`: + +```sh + $ git checkout -b my-topic origin/master +``` + +For release branch fixes, start the topic from `origin/release`, and by +convention use a topic name starting in `release-`: + +```sh + $ git checkout -b my-topic origin/release +``` + +(*You may visit the* Pro Git: Basic Branching *resource in [GitHelp] for +further information on working with branches.*) + +Edit files and create commits (repeat as needed). Add a prefix to your commit +message (see below). + +```sh + $ edit file1 file2 file3 +``` +(*To add data follow [these instructions](Documentation/Data.md#add-data).*) + +```sh + $ git add file1 file2 file3 + $ git commit +``` + +(*You may visit the* Pro Git: Recording Changes *resource in [GitHelp] for +further information on making changes and committing snapshots.*) + +Standard prefixes for BRAINSTools commit messages: + + * `BUG:` Fix for runtime crash or incorrect result + * `COMP:` Compiler error or warning fix + * `DOC:` Documentation change + * `ENH:` New functionality + * `PERF:` Performance improvement + * `STYLE:` No logic impact (indentation, comments) + * `WIP:` Work In Progress not ready for merge + +Share a Topic +------------- + +When a topic is ready for review and possible inclusion, share it by pushing +to Github pull request. + +Checkout the topic if it is not your current branch: + +```sh + $ git checkout my-topic +``` + +Check what commits will be pushed to Github for review: + +```sh + $ git prepush +``` + +Push commits in your topic branch for review by the community: + +```sh + $ git push mywriteaccessfork my-topic +``` + +ind your change in the [BRAINSTools Github page] instance and add reviewers, or provide additional documentation. + +Revise a Topic +-------------- + +If a topic is approved during review, skip to the +[next step](#merge-a-topic). Otherwise, revise the topic and push it back to +Github for another review. + +Checkout the topic if it is not your current branch: + +```sh + $ git checkout my-topic +``` + +To revise the most recent commit on the topic edit files and add changes +normally and then amend the commit: + +```sh + $ git commit --amend +``` + +(*You may visit the* Pro Git: Changing the Last Commit *resource in [GitHelp] +for further information on revising and rewriting your commit history.*) + +To revise commits further back on the topic, say the `3`rd commit back: + +```sh + $ git rebase -i HEAD~3 +``` + +(*Substitute the correct number of commits back, as low as `1`.*) + +Follow Git's interactive instructions. Preserve the `Change-Id:` line at the +bottom of each commit message. + +Return to the [Share a Topic](#share-a-topic) step to share the revised topic. + +(*You may visit the* Pro Git: Changing Multiple Commits *resource in [GitHelp] +for further information on changing multiple commits -i.e. not only the last +one, but further back in your history-, and the* Pro Git: Rebasing *resource on +taking all the changes that were committed on one branch and replaying them on +another one.*) + +Merge a Topic +------------- + +**Only authorized developers with [Git push access] may perform this step.** + +After a feature topic has been reviewed and approved in Github, merge it into +the upstream repository. + +Checkout the topic if it is not your current branch: + +```sh + $ git checkout my-topic +``` + +Merge the topic, which is originally forked off the `master` branch, to +`master` branch: + +```sh + $ git gerrit-merge +``` + +(*If the merge conflicts follow the printed instructions to resolve them.*) + +For bug fixes that are ready to be included in the next patch release, please +post a message in the [BRAINSTools discussion] for assistance. + +Here are the recommended steps to merge a topic to both release and master +branches, assuming the topic branch is forked off the release branch: + +```sh + $ git checkout release + $ git merge --no-ff my-topic + $ git push origin release +``` + +and do: + +```sh + $ git checkout master + $ git merge --no-ff release + $ git push origin master +``` + +to merge the `release` branch back to `master`. + +Delete a Topic +-------------- + +After a topic has been merged upstream, delete your local branch for the topic. + +Checkout and update the `master` branch: + +```sh + $ git checkout master + $ git pullall +``` + +Delete the local topic branch: + +```sh + $ git branch -d my-topic +``` + +The `branch -d` command works only when the topic branch has been correctly +merged. Use `-D` instead of `-d` to force the deletion of an unmerged topic +branch (**warning**: you could lose commits). + +[Git]: http://git-scm.com diff --git a/github/ISSUE_TEMPLATE.md b/github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000000..3e98e5bdbd --- /dev/null +++ b/github/ISSUE_TEMPLATE.md @@ -0,0 +1,22 @@ +## *Who* is the bug affecting? + + +## *What* is affected by this bug? + + +## *When* does this occur? + + +## *Where* on the platform does it happen? + + + +## *How* do we replicate the issue? + + + +## Expected behavior (i.e. solution) + + + +## Other Comments diff --git a/github/PULL_REQUEST_TEMPLATE.md b/github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..f1a28ad48b --- /dev/null +++ b/github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ +See the [CONTRIBUTING](CONTRIBUTING.md) guide. Specifically: + +Start BRAINSTools commit messages with a standard prefix (and a space): + + * BUG: fix for runtime crash or incorrect result + * COMP: compiler error or warning fix + * DOC: documentation change + * ENH: new functionality + * PERF: performance improvement + * STYLE: no logic impact (indentation, comments) + * WIP: Work In Progress not ready for merge + +Provide a short, meaningful message that describes the change you made. + +When the Pull Request (PR) is based on a single commit, the commit message is usually left as the PR message. + +A [reference to a related issue or pull request](https://help.github.com/articles/basic-writing-and-formatting-syntax/#referencing-issues-and-pull-requests) in your repository. You can automatically [close a related issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/) + +[@mentions](https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-people-and-teams) of the person or team responsible for reviewing proposed changes. + +Thanks for contributing to BRAINSTools!