📚 [just] cleaner list of recipes and document process (#4)

Author: chicks-net

.github/CONTRIBUTING.md

@@ -28,6 +28,47 @@ unless a screen shot is the only way to convey your problem.
 - Open a pull request on github.
 - Check the github actions on your PR to see if there's anything to fix.
 
+## Development requirements
+
+- `just`
+- `gh` - github CLI
+- `bash`
+
+## Development process
+
 The [justfile](../justfile) is used for centralizing snippets for build
 and many other purposes.  Run `just` anywhere in the repo to see which
 subcommands are available here.
+
+The full development cycle works via the command line.
+
+1. Starting with a cloned repo, run `just branch $some-name`
+1. Make some changes and make sure your last commit message convey your overall
+   purpose.
+1. Run `just pr` and it will create a PR based on your last commit message.
+1. Optionally, you can make other commits or update the PR description.
+1. Finally, `just merge` will merge the PR with squashed commit history and
+   cleaned up branches locally and remotely.  You'll end up with a repo back
+   on `main` (release) branch with the latest `git pull`ed.
+
+```bash
+% just
+just --list
+Available recipes:
+    [Compliance]
+    compliance_check  # our own compliance check
+
+    [Process]
+    branch branchname # start a new branch
+    merge             # merge PR and return to starting point
+    pr                # PR create 3.0
+    prweb             # view PR in web browser
+    sync              # escape from branch, back to starting point
+
+    [Utility]
+    utcdate           # print UTC date in ISO format
+
+    [example]
+    list              # list recipes (default works without naming it)
+Your justfile is waiting for more scripts and snippets
+```

justfile

@@ -22,7 +22,7 @@ sync:
 
 # PR create 3.0
 [group('Process')]
-pr: on_a_branch
+pr: _on_a_branch
     #!/usr/bin/env bash
     set -euxo pipefail # strict mode
 
@@ -60,24 +60,24 @@ pr: on_a_branch
 [group('Process')]
 merge:
     gh pr merge -s -d
-    just sync
+    just sync # mostly redundant, but just in case
 
 # start a new branch
 [group('Process')]
-branch branchname: main_branch
+branch branchname: _main_branch
     #!/usr/bin/env bash
     NOW=`just utcdate`
     git co -b "chicks/$NOW-{{ branchname }}"
 
 # view PR in web browser
 [group('Process')]
-prweb: on_a_branch
+prweb: _on_a_branch
     gh pr view --web
 
 # error if not on a git branch
 [group('sanity check')]
 [no-cd]
-on_a_branch:
+_on_a_branch:
     #!/bin/bash
 
     # thanks to https://stackoverflow.com/a/12142066/2002471
@@ -90,7 +90,7 @@ on_a_branch:
 # error if not on the release branch
 [group('sanity check')]
 [no-cd]
-main_branch:
+_main_branch:
     #!/bin/bash
 
     # thanks to https://stackoverflow.com/a/12142066/2002471