Merge pull request #148 from tstromberg/relnotes

Update release notes & docs for v1.2.0-beta.2

Author: tstromberg

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release Notes
 
+## Version 1.2.0-beta.2 - 2020-06-17
+
+Multiple improvements to the new Kanban display feature:
+
+* Improve reaction count display [#147](https://github.com/google/triage-party/pull/147)
+* Improve how Kanban is handled for unconfigured collections [#146](https://github.com/google/triage-party/pull/146)
+* Improve Kanban dashboard milestone handling & UI [#142](https://github.com/google/triage-party/pull/142)
+* Make timeline cache date calculation smarter [#141](https://github.com/google/triage-party/pull/141)
+* site: Make relative times more specific [#137](https://github.com/google/triage-party/pull/137)
+* Ensure that referenced PR's are the same age of parent issue [#136](https://github.com/google/triage-party/pull/136)
+
 ## Version 1.2.0-beta.1 - 2020-06-10
 
 * Add Kanban visualization support (display: kanban) [#125](https://github.com/google/triage-party/pull/125)

README.md

@@ -94,21 +94,19 @@ NOTE: Multi-player works best if the "Resolution" field of each rule has a clear
 
 ## Kanban mode (NEW)
 
-In v1.2.0-beta.1 and newer, you can see a Kanban dashboard presentation for a collection. The columns are based on the rule the issue was found in, and the rows are based on the assignee. To see a real-world example:
+![kanban mode](docs/images/kanban.png)
 
-* [minikube kanban dashboard](http://tinyurl.com/minikube-kanban)
-* [minikube kanban config](https://github.com/google/triage-party/blob/0ad4f584ac0db13a96548d3eca9d05e91e0b1a40/config/examples/minikube.yaml#L108)
-
-CAVEATS: In v1.2.0-beta.1, the Kanban view only works for issues that are within a milestone. You'll need to add these configuration lines to the collection to make this view visable:
+In v1.2.0, pages can now be displayed as a Kanban dashboard. The columns are based on the rule the issue was fonud in, and the rows are swim-lanes based on the assignee. To see a real-world example:
 
+* [minikube kanban dashboard](http://tinyurl.com/minikube-kanban)
+* [minikube kanban config](https://github.com/google/triage-party/blob/569782c961d66468e0def2d4f8b54acd104b02f4/config/examples/minikube.yaml#L111)
 
-```
-    display: kanban
-    overflow: 3
-    selector: milestone
-```
+Best practices for designing a useful Kanban dashboard:
 
-You may also find `dedup: true` to be a useful configuration option. When v1.2.0 ships, all collections will be viewable as a Kanban dashboard using the /k/id URL path.
+* Rules should be designed and ordered in a way that represents progress: `Not started` -> `Started` -> `Under Review` -> `Completed`
+* Rules work best when they are mutually excusive (no issue matches multiple rules)
+* If a collection should be displayed in Kanban form by default, specify `display: kanban` in its configuration.
+* For velocity measurements and time estimate support, create a rule named `__velocity__` containing recently closed issues to include. See the example configuration.
 
 ## Data freshness
 

docs/config.md

@@ -7,6 +7,17 @@ Triage Party includes with two example configurations that are useful to get sta
 * [config](../config/config.yaml): uses label regular expressions that work for most GitHub projects
 * [kubernetes](../config/examples/kubernetes.yaml): for projects that use Kubernetes-style labels, particularly prioritization
 
+## Settings
+
+There are only a handful of site-wide settings worth mentioning:
+
+* `name`: Name of the your Triage Party site
+* `min_similarity`: On a scale from 0-1, how similar do two titles need to be before they are labelled as similar. The default is 0 (disabled), but a useful setting is 0.75
+* `repos`: A list of repositories to query by default
+* `member-roles`: Which GitHub roles to consider as project members
+* `members`: A list of people to hard-code as members of the project
+
+
 ## Collections
 
 Each page within Triage Party is represented by a `collection`. Each collection references a list of `rules` that can be shared across collections. Here is a simple collection, which creates a page named `I like soup!`, containing two rules:
@@ -20,6 +31,15 @@ collections:
       - many-reactions
 ```
 
+### Settings
+
+For collections, there are a few useful settings to mention:
+
+* `description`: description shown for this collection
+* `dedup` (bool): whether to filter out duplicate issues/PR's that show up among multiple rules
+* `display`: whether to show this page as `kanban` or `default`
+* `overflow`: flag issues if there are issues within a Kanban cell above or equal to this number
+
 ## Rules
 
 The first rule, `discuss`, include all items labelled as `triage/discuss`, whether they are pull requests or issues, open or closed.
@@ -110,16 +130,23 @@ Triage Party has an automatic tagging mechanism that adds annotations which can
 * `member-last`: a member of the organization was the last commenter
 * `author-last`: the original author was the last commenter
 * `assigned`: the issue or PR has been assigned to someone
+* `assignee-updated`: the issue has been updated by its assignee
 * `closed`: the issue or PR has been closed
+* `merged`: PR was merged
+* `draft`: PR is a draft PR
 * `similar`: the issue or PR appears to be similar to another
-* `new-commits`: the PR has new commits since the last member response
+* `open-milestone`: the issue or PR appears in an open milestone
 
 To determine review state, we support the following tags:
 
 * `approved`: Last review was an approval
-* `reviewed-with-comment`: Last review was a comment
 * `changes-requested`: Last review was a request for changes
+* `reviewed-with-comment`: Last review was a comment
+* `new-commits`: the PR has new commits since the last member response
 * `unreviewed`: PR has never been reviewed
 * `pushed-after-approval`: PR was pushed to after approval
 
 The afforementioned PR review tags are also added to linked issues, though with a `pr-` prefix. For instance, `pr-approved`.
+
+## Display configuration
+