Create recipes to generate project planning docs

documentation/justfile

@@ -1,4 +1,5 @@
 set dotenv-load := false
+set positional-arguments
 
 COLOR := "\\033[0;35m"
 NO_COLOR := "\\033[0m"
@@ -18,6 +19,54 @@ install:
 # Sphinx #
 ##########
 
+# Create a new project with proposal and, optionally, implementation plans
+init-project project_name *ip_names:
+    #!/usr/bin/env bash
+    set -eo pipefail
+    TIMESTAMP=$(date '+%Y%m%d')
+    DATE=$(date '+%Y-%m-%d')
+    PROJECTFS="{{ replace(lowercase(project_name), ' ', '_') }}"
+    # Create project directory
+    mkdir "projects/proposals/$PROJECTFS"
+    # Create project directory index
+    INDEXPATH="projects/proposals/$PROJECTFS/index.md"
+    sed \
+      -e '1,3d;$d' \
+      -e 's/{Project title}/{{ project_name }}/g' \
+      projects/templates/index.md > $INDEXPATH
+    echo "Project index: $INDEXPATH"
+    # Create project proposal
+    PROPOSALPATH="projects/proposals/$PROJECTFS/$TIMESTAMP-project_proposal.md"
+    sed \
+      -e '1,3d;$d' \
+      -e 's/{Project proposal title}/{{ project_name }}/g' \
+      -e "s/{YYYY-MM-DD}/$DATE/g" \
+      projects/templates/project_proposal.md > $PROPOSALPATH
+    echo "Project proposal: $PROPOSALPATH"
+    # Create implementation plans
+    shift
+    for IP in "$@"; do
+        just create-ip "$PROJECTFS" "$IP"
+    done
+
+# Create a new implementation plan in the given directory
+create-ip project_dirname ip_name:
+    #!/usr/bin/env bash
+    set -eo pipefail
+    TIMESTAMP=$(date '+%Y%m%d')
+    DATE=$(date '+%Y-%m-%d')
+    IPFS="{{ replace(lowercase(ip_name), ' ', '_') }}"
+    PROPOSALFS=$(find "projects/proposals/{{ project_dirname }}" -maxdepth 1 -name '*project_proposal.md')
+    # Create implementation plan
+    IPPATH="projects/proposals/{{ project_dirname }}/$TIMESTAMP-implementation_plan_$IPFS.md"
+    sed \
+      -e '1,3d;$d' \
+      -e "s/{YYYY-MM-DD}/$DATE/g" \
+      -e 's/{Implementation plan title}/{{ ip_name }}/g' \
+      -e "s|{Project proposal path}|/$PROPOSALFS|g" \
+      projects/templates/implementation_plan.md > $IPPATH
+    echo "Implementation plan: $IPPATH"
+
 # Serve a live-reload documentation site
 live port="50230": clean
     pipenv run sphinx-autobuild -b html . _serve/ --port {{ port }}

documentation/projects/planning.md

@@ -24,23 +24,53 @@ maintainer in the #openverse channel of the
 ## Where documents are kept, how they are named, and how they are reviewed
 
 For each project, planning documents should be kept in the
-`/documentation/projects/proposals/` directory of this repository. Each project
-should have its own subdirectory. Projects predating this document have been
-updated to follow this structure. Individual documents should be date-stamped in
-the `YYYYMMDD` format. An example of this entire structure follows:
+`/documentation/projects/proposals/` directory of this repository.
+
+- Each project should have its own subdirectory. This is named after the
+  project, converted to `snake_case`.
+- Individual documents should be date-stamped in the `YYYYMMDD` format.
+- This subdirectory must contain an `index.md` file in a
+  [standard format](/projects/templates/index.md).
+- This subdirectory must contain a project proposal in a
+  [standard format](/projects/templates/project_proposal.md). This is named
+  `YYYYMMDD-project_proposal.md`.
+- This subdirectory can contain any number of implementation plans, each in a
+  [standard format](/projects/templates/implementation_plan.md). These are named
+  `YYYYMMDD-implementation_plan_<name>.md` where the `<name>` is the plan name,
+  converted to `snake_case`.
+
+Refer to the existing projects for reference.
+
+````{tip}
+You can initialise a new project using the `just` recipe `init-project`. It
+accepts one argument as the project name, followed optionally by any number of
+implementation plans.
+
+```bash
+$ just documentation/init-project 'Project name' 'First IP' 'Second IP'
+```
+
+This will create the directory structure for your project with the specified
+implementation plans.
 
 ```
-| documentation/projects/proposals/
-   | service_metrics/
-      - YYYYMMDD-project_proposal.md
-      - YYYYMMDD-implementation_plan.md
-   | 3d_model_support/
-      - YYYYMMDD-project_proposal.md
-      - YYYYMMDD-implementation_plan_(catalogue).md
-      - YYYYMMDD-implementation_plan_(api).md
-      - YYYYMMDD-implementation_plan_(frontend).md
+documentation/projects/proposals/
+└─ project_name/
+   ├─ index.md
+   ├─ 20230101-project_proposal.md
+   ├─ 20230101-implementation_plan_first_ip.md
+   └─ 20230101-implementation_plan_second_ip.md
 ```
 
+If you already have a project directory and want to add a new implementation
+plan, you can use the `just` recipe `create-ip`. It accepts the directory name
+(not full path) of the project and the plan name as arguments.
+
+```bash
+$ just documentation/create-ip project_name 'New IP'
+```
+````
+
 Using subdirectories makes it slightly easier to navigate an ever-growing list
 of planning documents. This is especially the case in projects similar to the 3D
 Models project in the example above that may require multiple implementation
@@ -58,6 +88,10 @@ Because project documents prefix their titles with a date, we can safely use a g
 Refer to the [project `index.md` templates](/projects/templates/index.md) for a starting point.
 ```
 
+```{note}
+Projects predating this document have been updated to follow this structure.
+```
+
 All project documentation can be authored with any tool, but must be written in
 [MyST/Commonmark+ flavored Markdown](https://myst-parser.readthedocs.io/en/latest/syntax/reference.html).
 
@@ -147,7 +181,7 @@ section of this document.
 
 ### Kickoff (`status: In Kickoff`)
 
-- [Kickoff/Project Proposal template](./templates/project-proposal.md)
+- [Kickoff/Project Proposal template](./templates/project_proposal.md)
 
 In the kickoff stage, a **project proposal** is written and shared with the team
 by the project lead. The primary goals of this document are that of discovery;
@@ -239,7 +273,7 @@ them.
 
 ### Implementation Plans (`status: In RFC`)
 
-- [Implementation Plan Template](./templates/implementation-plan.md)
+- [Implementation Plan Template](./templates/implementation_plan.md)
 
 Implementation plans are the next type of RFC created for a project. The main
 goal of an implementation plan is to produce a discrete and ordered list of

documentation/projects/templates/implementation-plan.md → documentation/projects/templates/implementation_plan.md

@@ -1,7 +1,7 @@
-# Implementation Plan Template
+# Template: Implementation Plan
 
 ```md
-# {YYYY-MM-DD} Implementation Plan: {Piece of project or project being implemented}
+# {YYYY-MM-DD} Implementation Plan: {Implementation plan title}
 
 **Author**: @username
 
@@ -20,7 +20,7 @@
 <!-- Enumerate any references to other documents/pages, including milestones and other plans -->
 
 - [Project Thread]()
-- [Project Proposal]()
+- [Project Proposal]({Project proposal path})
 
 ## Overview
 

documentation/projects/templates/index.md

@@ -1,4 +1,4 @@
-# Project directory `index.md` template
+# Template: Project Directory `index.md`
 
 ````md
 # {Project title}

documentation/projects/templates/project-proposal.md → documentation/projects/templates/project_proposal.md

@@ -1,7 +1,7 @@
-# Project Proposal Template
+# Template: Project Proposal
 
 ```md
-# {YYYY-MM-DD} Project Proposal
+# {YYYY-MM-DD} Project Proposal: {Project proposal title}
 
 **Author**: @username