2016-10-28 07:18:25 +00:00
# Serverless Kanban Board for GitHub Issues
[![issues][gh-board-image]][gh-board-url]
[![dependency status][dependency-image]][dependency-url]
[![dev dependency status][dev-dependency-image]][dev-dependency-url]
2016-03-09 15:28:13 +00:00
Why waste time and money paying for a Ticket Tracker when you already work in GitHub? Now, you don't have to.
- [Features ](#features )
- [Multiple Repositories ](#multiple-repositories )
- [Linked Issues and Pull Requests ](#linked-issues-and-pull-requests )
- [Real-Time Collaboration ](#real-time-collaboration )
- [Filtering ](#filtering )
- [Milestone Planning ](#milestone-planning )
- [Moving Cards ](#moving-cards )
- [Task Lists ](#task-lists )
- [CI Status and Merge Conflict ](#ci-status-and-merge-conflict )
2016-04-02 01:01:20 +00:00
- [Issue Images ](#issue-images )
2016-04-04 22:56:47 +00:00
- [Pull Request to non-default branch ](#pull-request-to-non-default-branch )
2016-04-15 17:29:53 +00:00
- [Batch-Edit Labels in Multiple Repositories ](#batch-edit-labels-in-multiple-repositories )
2016-04-09 22:28:29 +00:00
- [Burnup Chart ](#burnup-chart )
2016-03-25 03:45:49 +00:00
- [Easter Eggs ](#easter-eggs )
2016-03-09 15:28:13 +00:00
- [Examples ](#examples )
- [Development ](#development )
- [How Does it Work? ](#how-does-it-work )
- [TODO List ](#todo-list )
2015-09-08 20:21:07 +00:00
2016-03-09 15:28:13 +00:00
# Features
2015-09-08 20:21:07 +00:00
2016-03-09 15:28:13 +00:00
### Multiple Repositories
2015-09-08 20:21:07 +00:00
2016-03-09 15:28:13 +00:00
Multiple Repositories in an organization can be shown on a board (from different organizations too!). The repository is shown in gray next to the Issue number.
2015-09-08 20:21:07 +00:00
2016-03-09 15:28:13 +00:00
2015-09-08 20:21:07 +00:00
2016-03-09 15:28:13 +00:00
### Linked Issues and Pull Requests
Just add `#123` or `orgName/RepoName#123` to the Issue or Pull Request body and linked Issues will show up with the column they are in, both below the Card and in the preview popup.
### Real-Time Collaboration
By clicking the :pencil2: icon next to the card title, multiple people can edit the Issue Body at once (ie in a meeting), and when editing is done, one person clicks < kbd > Save to GitHub< / kbd > .
Features:
- send anyone the link to edit
- real-time preview of Markdown
- references to Issues show with their state and board column
- Sequence, State, Gantt, and other diagrams are supported (using [mermaid ](https://knsv.github.io/mermaid/ ))
<!--  -->
### Filtering
- cards can be filtered by label, milestone, board column, or user
- filters can be inclusive as well as exclusive
2015-09-10 07:14:37 +00:00
2016-03-09 15:28:13 +00:00
### Milestone Planning
2015-09-29 05:01:44 +00:00
2016-03-09 15:28:13 +00:00
When doing Milestone (or Sprint) planning there is a view to easily move cards into milestones
2015-09-29 05:01:44 +00:00
2016-03-09 15:28:13 +00:00
2015-09-29 05:01:44 +00:00
2016-03-09 15:28:13 +00:00
### Moving Cards
2015-09-29 05:01:44 +00:00
2016-03-09 15:28:13 +00:00
Cards can be dragged from one column to the next
2015-09-10 07:14:37 +00:00
2016-03-09 15:28:13 +00:00
2015-09-08 20:21:07 +00:00
2016-03-09 15:28:13 +00:00
### Task Lists
2015-09-15 04:41:32 +00:00
2016-03-09 15:28:13 +00:00
By using the `- [ ]` notation in the body of an Issue or Pull Request, the progress of an Issue is shown in the top-right corner of a Card.
2015-09-11 20:26:57 +00:00
2016-03-09 15:28:13 +00:00
2015-09-29 05:01:44 +00:00
2016-03-09 15:28:13 +00:00
<!--
 -->
### CI Status and Merge Conflict
- CI Status shows up as a green :heavy_check_mark: or a red :x: on the top-right corner of a card
- Merge conflicts are shown with a yellow :warning: and have a diagonal striped background
<!--  -->
2016-03-28 05:53:15 +00:00
2016-04-09 22:28:29 +00:00
### Burnup Chart
2016-03-28 05:53:15 +00:00
2016-04-09 22:28:29 +00:00
[Why Burnup instead of Burndown? ](http://brodzinski.com/2012/10/burn-up-better-burn-down.html )
Shows a burnup chart for a Milestone (ie "Sprint" or "Iteration").
2016-03-28 05:53:15 +00:00
If you use select multiple repositories it will include all of them.
2016-04-09 22:28:29 +00:00
It also skips when nothing was opened or closed that day/month/year (useful to see weekends or holidays).
2016-03-28 05:53:15 +00:00
2016-04-02 01:01:20 +00:00
# Issue Image
If an Issue or Pull Request contains an image then it will be shown in the Issue
2016-04-04 22:56:47 +00:00
### Pull Request to non-default branch
Sometimes Pull Requests go to a branch other than the main branch. This makes it clear when that happens.
2016-04-15 17:29:53 +00:00
### Batch-Edit Labels in Multiple Repositories
If you need to rename a column or remove a duplicate label you can get to this page from the Settings dropdown next to the filter link.
2016-04-04 22:56:47 +00:00
2016-03-25 03:45:49 +00:00
# Easter Eggs
Plus, it comes with totally useful easter eggs you can unlock!
2016-03-09 15:28:13 +00:00
# Examples
Just specify a GitHub repository in the URL and off you go!
- [openstax/tutor-js ](http://philschatz.com/gh-board/#/r/openstax:tutor-js )
- [openstax/tutor-js + tutor-server ](http://philschatz.com/gh-board/#/r/openstax:tutor-js|tutor-server ) (multiple repositories)
2016-04-25 04:05:37 +00:00
- [huboard/huboard ](http://philschatz.com/gh-board/#/r/huboard:huboard )
2016-03-09 15:28:13 +00:00
- [jquery/jquery ](http://philschatz.com/gh-board/#/r/jquery:jquery )
- Or wildcards! (must be logged in) using `http://philschatz.com/gh-board/#/r/openstax:tutor-js|*`
2015-10-23 17:57:43 +00:00
2015-09-11 20:26:57 +00:00
# Development
- `npm start` to start up the dev server and go to `http://localhost:8080`
- `npm run build` to generate the JS and CSS files in `./dist`
2016-03-09 15:28:13 +00:00
### How Does it Work?
- JavaScript calls the GitHub API and pulls in the Issues for a given repository.
- Since there is no server to do OAuth, people need to provide a GitHub token which is stored in `localStorage`
- It uses the first repository to get the Issue Labels and Milestones.
- There are special Labels which represent the board columns (in the format `# - Column Title` )
- To be a "Good API Citizen" `gh-board` uses eTags provided by GitHub and saves them in `localStorage` (or `IndexedDB` )
### Hosting your own Forked Version
1. create a fork
2. switch to the `gh-pages` branch
3. make a commit and push it to `gh-pages` (to trigger GitHub to start hosting the files)
4. go to `https://${USERNAME}.github.io/gh-board/`
5. To make edits and push them up on GitHub
- make edits in the src directory in `gh-pages`
- run `npm run build`
- commit and push
2015-09-08 20:21:07 +00:00
# TODO List
2015-09-10 07:14:37 +00:00
- [x] combine Issue and the Pull Requests that fixes it
- [x] handle dragging in multiple repos:
2015-09-08 20:21:07 +00:00
1. auto-create the label in the new repo (confirm first)
2015-09-15 04:41:32 +00:00
- [x] add checkbox for selecting multiple repos in dashboard
- [x] select between Issue-centric and PullRequest-centric view
2015-09-28 08:20:55 +00:00
- [x] support milestone (sprint) planning by making each milestone a column
2016-04-22 19:58:37 +00:00
- [x] show labels unique to each repository
2016-04-24 19:34:18 +00:00
- [x] linked Issues & PR's should include the title
2016-05-05 00:33:33 +00:00
- [x] collaboratively edit Milestones and any GitHub file by going to `/p-file/:repoOwner/:repoName/:branch/path-to-file`
- [x] add a list view in addition to a board
- [ ] Sort by Due At, Updated At, and ascending/descending
2016-04-22 19:58:37 +00:00
- [ ] add a way to add labels/milestones to an Issue (autocreate the label/milestone in the repo)
- [ ] cache issues-updated-since requests and CI status requests in Session Storage instead of IndexedDB so they can be cleared easier
2016-05-05 00:33:33 +00:00
- [ ] add effort labels XS, S, M, L, XL
- [ ] add GitHub search
2016-10-28 07:18:25 +00:00
[gh-board-image]: https://img.shields.io/github/issues/philschatz/gh-board.svg?label=Issues%20%28gh-board%29
[gh-board-url]: http://philschatz.com/gh-board/
[travis-image]: https://img.shields.io/travis/philschatz/gh-board.svg
[travis-url]: https://travis-ci.org/philschatz/gh-board
[dependency-image]: https://img.shields.io/david/philschatz/gh-board.svg
[dependency-url]: https://david-dm.org/philschatz/gh-board
[dev-dependency-image]: https://img.shields.io/david/dev/philschatz/gh-board.svg
[dev-dependency-url]: https://david-dm.org/philschatz/gh-board?type=dev
