Edit README (#13)

Author: stefanv

README.md

@@ -1,6 +1,6 @@
 # changelist
 
-Prepare an automatic changelog from GitHub pull requests
+Prepare an automatic changelog from GitHub pull requests.
 
 _This project is currently in its alpha stage and might be incomplete or change a lot!_
 
@@ -12,7 +12,8 @@ pip install changelist
 
 ## Set up your repository
 
-All PRs must have one of the following labels:
+To categorize merged PRs in the changelist, each PR
+must have have one of the following labels:
 
 - `type: Highlights`
 - `type: New features`
@@ -24,12 +25,16 @@ All PRs must have one of the following labels:
 - `type: Documentation`
 - `type: Infrastructure`
 
+This list will soon be configurable.
+
 ### Label checking
 
-To ensure that each PR has one of the above labels attached to it,
-we recommend adding the following to `.github/workflows/label-check.yaml`:
+To ensure that each PR has an associated `type: ` label,
+we recommend adding an action that fails CI if the label is missing.
 
-```
+To do so, place the following in `.github/workflows/label-check.yaml`:
+
+```yaml
 name: Labels
 
 on:
@@ -53,9 +58,13 @@ jobs:
 
 ### Milestones
 
-We also recommend adding `.github/workflows/milestone-merged-prs.yaml`:
+Often, it is helpful to have milestones that reflect the actual PRs
+merged. We therefore recommend adding an action that attached the
+next open milestone to any merged PR.
 
-```
+To do so, place the following in `.github/workflows/milestone-merged-prs.yaml`:
+
+```yaml
 name: Milestone
 
 on:
@@ -84,3 +93,8 @@ See https://github.com/scientific-python/attach-next-milestone-action for more i
 export GH_TOKEN='...'
 changelist scikit-image/scikit-image v0.21.0 main
 ```
+
+The script requires a [GitHub personal access
+token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+The token does not need any permissions, since it is used only to
+increase query limits.