diff --git a/documentation/justfile b/documentation/justfile index a27914a3166..4a88114754f 100644 --- a/documentation/justfile +++ b/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 +create-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 }} diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 13cb175165b..cc3b2ed7b97 100644 --- a/documentation/projects/planning.md +++ b/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_.md` where the `` 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 `create-project`. It +accepts one argument as the project name, followed optionally by any number of +implementation plans. + +```bash +$ just documentation/create-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 diff --git a/documentation/projects/templates/implementation-plan.md b/documentation/projects/templates/implementation_plan.md similarity index 96% rename from documentation/projects/templates/implementation-plan.md rename to documentation/projects/templates/implementation_plan.md index f07797df01b..69bea9f76e2 100644 --- a/documentation/projects/templates/implementation-plan.md +++ b/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 @@ - [Project Thread]() -- [Project Proposal]() +- [Project Proposal]({Project proposal path}) ## Overview diff --git a/documentation/projects/templates/index.md b/documentation/projects/templates/index.md index 8f0d93cb8ff..2d669ace84c 100644 --- a/documentation/projects/templates/index.md +++ b/documentation/projects/templates/index.md @@ -1,4 +1,4 @@ -# Project directory `index.md` template +# Template: Project Directory `index.md` ````md # {Project title} diff --git a/documentation/projects/templates/project-proposal.md b/documentation/projects/templates/project_proposal.md similarity index 95% rename from documentation/projects/templates/project-proposal.md rename to documentation/projects/templates/project_proposal.md index c517a3b778e..25908249162 100644 --- a/documentation/projects/templates/project-proposal.md +++ b/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