From 7d3c5a956a40ba63b5639f2dcff62aad15b705bc Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Wed, 27 Sep 2023 12:02:09 +0400 Subject: [PATCH 01/10] Use underscore in file names and add "Template:" prefix to title --- .../{implementation-plan.md => implementation_plan.md} | 2 +- documentation/projects/templates/index.md | 2 +- .../templates/{project-proposal.md => project_proposal.md} | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename documentation/projects/templates/{implementation-plan.md => implementation_plan.md} (99%) rename documentation/projects/templates/{project-proposal.md => project_proposal.md} (98%) diff --git a/documentation/projects/templates/implementation-plan.md b/documentation/projects/templates/implementation_plan.md similarity index 99% rename from documentation/projects/templates/implementation-plan.md rename to documentation/projects/templates/implementation_plan.md index f07797df01b..2560df3426b 100644 --- a/documentation/projects/templates/implementation-plan.md +++ b/documentation/projects/templates/implementation_plan.md @@ -1,4 +1,4 @@ -# Implementation Plan Template +# Template: Implementation Plan ```md # {YYYY-MM-DD} Implementation Plan: {Piece of project or project being implemented} 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 98% rename from documentation/projects/templates/project-proposal.md rename to documentation/projects/templates/project_proposal.md index c517a3b778e..4f41e160805 100644 --- a/documentation/projects/templates/project-proposal.md +++ b/documentation/projects/templates/project_proposal.md @@ -1,4 +1,4 @@ -# Project Proposal Template +# Template: Project Proposal ```md # {YYYY-MM-DD} Project Proposal From 469e5843155082dfe2f9ec560040ded44a225817 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Wed, 27 Sep 2023 12:03:30 +0400 Subject: [PATCH 02/10] Add stencils for text injection --- documentation/projects/templates/implementation_plan.md | 4 ++-- documentation/projects/templates/project_proposal.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/projects/templates/implementation_plan.md b/documentation/projects/templates/implementation_plan.md index 2560df3426b..69bea9f76e2 100644 --- a/documentation/projects/templates/implementation_plan.md +++ b/documentation/projects/templates/implementation_plan.md @@ -1,7 +1,7 @@ # 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/project_proposal.md b/documentation/projects/templates/project_proposal.md index 4f41e160805..25908249162 100644 --- a/documentation/projects/templates/project_proposal.md +++ b/documentation/projects/templates/project_proposal.md @@ -1,7 +1,7 @@ # Template: Project Proposal ```md -# {YYYY-MM-DD} Project Proposal +# {YYYY-MM-DD} Project Proposal: {Project proposal title} **Author**: @username From c407fb5f07016e35db1fc37d259b999c0a9f6684 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Wed, 27 Sep 2023 15:49:05 +0400 Subject: [PATCH 03/10] Codify rules for project planning files and add `just` recipes --- documentation/justfile | 43 +++++++++++++++++++++ documentation/projects/planning.md | 60 +++++++++++++++++++++++------- 2 files changed, 90 insertions(+), 13 deletions(-) diff --git a/documentation/justfile b/documentation/justfile index a27914a3166..b2e7bb3ff09 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,48 @@ install: # Sphinx # ########## +# Create a new project with proposal and implementation plans +init-project name *ips: + #!/usr/bin/env bash + set -eo pipefail + TIMESTAMP=$(date '+%Y%m%d') + DATE=$(date '+%Y-%m-%d') + PROJECTFS="{{ replace(lowercase(name), ' ', '_') }}" + # Create project directory + mkdir "projects/proposals/$PROJECTFS" + # Create project directory index + sed \ + -e '1,3d;$d' \ + -e 's/{Project title}/{{ name }}/g' \ + projects/templates/index.md > "projects/proposals/$PROJECTFS/index.md" + # Create project proposal + sed \ + -e '1,3d;$d' \ + -e 's/{Project proposal title}/{{ name }}/g' \ + -e "s/{YYYY-MM-DD}/$DATE/g" \ + projects/templates/project_proposal.md > "projects/proposals/$PROJECTFS/$TIMESTAMP-project_proposal.md" + # Create implementation plans + shift + for IP in "$@"; do + just create-ip "projects/proposals/$PROJECTFS" "$IP" + done + +# Create a new implementation plan in the given directory +create-ip directory name: + #!/usr/bin/env bash + set -eo pipefail + TIMESTAMP=$(date '+%Y%m%d') + DATE=$(date '+%Y-%m-%d') + IPFS="{{ replace(lowercase(name), ' ', '_') }}" + PROPOSALFS=$(find "{{ directory }}" -maxdepth 1 -name '*project_proposal.md') + # Create implementation plan + sed \ + -e '1,3d;$d' \ + -e "s/{YYYY-MM-DD}/$DATE/g" \ + -e 's/{Implementation plan title}/{{ name }}/g' \ + -e "s|{Project proposal path}|/$PROPOSALFS|g" \ + projects/templates/implementation_plan.md > "{{ directory }}/$TIMESTAMP-implementation_plan_$IPFS.md" + # 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..95bb3d75e3f 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 name 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 `init-project`. It +accepts one argument as the project name followed 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 project directory +and the plan name as arguments. + +```bash +$ just documentation/create-ip project/proposals/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). From d323386fbe89200f608c340b576c1624dd048d3a Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Wed, 27 Sep 2023 18:04:53 +0400 Subject: [PATCH 04/10] Update links --- documentation/projects/planning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 95bb3d75e3f..759ed55590f 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -181,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; @@ -273,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 From 14f0d3d64f564cf9aa1832d9b947d408b3326410 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Fri, 29 Sep 2023 12:58:36 +0400 Subject: [PATCH 05/10] Log the paths to the created files --- documentation/justfile | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/documentation/justfile b/documentation/justfile index b2e7bb3ff09..bd3f06691f3 100644 --- a/documentation/justfile +++ b/documentation/justfile @@ -29,16 +29,20 @@ init-project name *ips: # 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}/{{ name }}/g' \ - projects/templates/index.md > "projects/proposals/$PROJECTFS/index.md" + 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}/{{ name }}/g' \ -e "s/{YYYY-MM-DD}/$DATE/g" \ - projects/templates/project_proposal.md > "projects/proposals/$PROJECTFS/$TIMESTAMP-project_proposal.md" + projects/templates/project_proposal.md > $PROPOSALPATH + echo "Project proposal: $PROPOSALPATH" # Create implementation plans shift for IP in "$@"; do @@ -54,12 +58,14 @@ create-ip directory name: IPFS="{{ replace(lowercase(name), ' ', '_') }}" PROPOSALFS=$(find "{{ directory }}" -maxdepth 1 -name '*project_proposal.md') # Create implementation plan + IPPATH="{{ directory }}/$TIMESTAMP-implementation_plan_$IPFS.md" sed \ -e '1,3d;$d' \ -e "s/{YYYY-MM-DD}/$DATE/g" \ -e 's/{Implementation plan title}/{{ name }}/g' \ -e "s|{Project proposal path}|/$PROPOSALFS|g" \ - projects/templates/implementation_plan.md > "{{ directory }}/$TIMESTAMP-implementation_plan_$IPFS.md" + projects/templates/implementation_plan.md > $IPPATH + echo "Implementation plan: $IPPATH" # Serve a live-reload documentation site live port="50230": clean From 2a777ca68ce44f07d33acdfdae5178c0394a4dc4 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Fri, 29 Sep 2023 13:01:09 +0400 Subject: [PATCH 06/10] Specify that IPs are optional --- documentation/justfile | 2 +- documentation/projects/planning.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/justfile b/documentation/justfile index bd3f06691f3..358b49db24a 100644 --- a/documentation/justfile +++ b/documentation/justfile @@ -19,7 +19,7 @@ install: # Sphinx # ########## -# Create a new project with proposal and implementation plans +# Create a new project with proposal and, optionally, implementation plans init-project name *ips: #!/usr/bin/env bash set -eo pipefail diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 759ed55590f..491971b0d30 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -43,7 +43,7 @@ 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 by any number of +accepts one argument as the project name, followed optionally by any number of implementation plans. ```bash From c68ffef5ab5eb1743b3ebe6c77c18f0237437e78 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Fri, 29 Sep 2023 13:07:57 +0400 Subject: [PATCH 07/10] Fix typos --- documentation/projects/planning.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 491971b0d30..2e54f4f7f8e 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -26,8 +26,8 @@ maintainer in the #openverse channel of the For each project, planning documents should be kept in the `/documentation/projects/proposals/` directory of this repository. -- Each project should have its own subdirectory. This is name after the project, - converted to `snake_case`. +- 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). @@ -67,7 +67,7 @@ plan, you can use the `just` recipe `create-ip`. It accepts the project director and the plan name as arguments. ```bash -$ just documentation/create-ip project/proposals/project_name 'New IP' +$ just documentation/create-ip projects/proposals/project_name 'New IP' ``` ```` From 074c2b73a878472dec59dfb1f9f56d7d745589b8 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Fri, 29 Sep 2023 13:09:38 +0400 Subject: [PATCH 08/10] Use clearer arg names in recipes --- documentation/justfile | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/documentation/justfile b/documentation/justfile index 358b49db24a..12f957b22fd 100644 --- a/documentation/justfile +++ b/documentation/justfile @@ -20,26 +20,26 @@ install: ########## # Create a new project with proposal and, optionally, implementation plans -init-project name *ips: +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(name), ' ', '_') }}" + 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}/{{ name }}/g' \ + -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}/{{ name }}/g' \ + -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" @@ -50,19 +50,19 @@ init-project name *ips: done # Create a new implementation plan in the given directory -create-ip directory name: +create-ip directory ip_name: #!/usr/bin/env bash set -eo pipefail TIMESTAMP=$(date '+%Y%m%d') DATE=$(date '+%Y-%m-%d') - IPFS="{{ replace(lowercase(name), ' ', '_') }}" + IPFS="{{ replace(lowercase(ip_name), ' ', '_') }}" PROPOSALFS=$(find "{{ directory }}" -maxdepth 1 -name '*project_proposal.md') # Create implementation plan IPPATH="{{ directory }}/$TIMESTAMP-implementation_plan_$IPFS.md" sed \ -e '1,3d;$d' \ -e "s/{YYYY-MM-DD}/$DATE/g" \ - -e 's/{Implementation plan title}/{{ name }}/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" From 18798f739033c7c86e9ef15e45c80325318e52ba Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Fri, 29 Sep 2023 13:10:17 +0400 Subject: [PATCH 09/10] Require project directory name instead of path --- documentation/justfile | 8 ++++---- documentation/projects/planning.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/documentation/justfile b/documentation/justfile index 12f957b22fd..d6e8e0dd29a 100644 --- a/documentation/justfile +++ b/documentation/justfile @@ -46,19 +46,19 @@ init-project project_name *ip_names: # Create implementation plans shift for IP in "$@"; do - just create-ip "projects/proposals/$PROJECTFS" "$IP" + just create-ip "$PROJECTFS" "$IP" done # Create a new implementation plan in the given directory -create-ip directory ip_name: +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 "{{ directory }}" -maxdepth 1 -name '*project_proposal.md') + PROPOSALFS=$(find "projects/proposals/{{ project_dirname }}" -maxdepth 1 -name '*project_proposal.md') # Create implementation plan - IPPATH="{{ directory }}/$TIMESTAMP-implementation_plan_$IPFS.md" + IPPATH="projects/proposals/{{ project_dirname }}/$TIMESTAMP-implementation_plan_$IPFS.md" sed \ -e '1,3d;$d' \ -e "s/{YYYY-MM-DD}/$DATE/g" \ diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 2e54f4f7f8e..791abc9943b 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -63,11 +63,11 @@ documentation/projects/proposals/ ``` 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 project directory -and the plan name as arguments. +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 projects/proposals/project_name 'New IP' +$ just documentation/create-ip project_name 'New IP' ``` ```` From 1b2334cbf93026654b0570f71114a36292763693 Mon Sep 17 00:00:00 2001 From: Dhruv Bhanushali Date: Thu, 5 Oct 2023 05:17:07 +0000 Subject: [PATCH 10/10] Replace 'init' with 'create' --- documentation/justfile | 2 +- documentation/projects/planning.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/justfile b/documentation/justfile index d6e8e0dd29a..4a88114754f 100644 --- a/documentation/justfile +++ b/documentation/justfile @@ -20,7 +20,7 @@ install: ########## # Create a new project with proposal and, optionally, implementation plans -init-project project_name *ip_names: +create-project project_name *ip_names: #!/usr/bin/env bash set -eo pipefail TIMESTAMP=$(date '+%Y%m%d') diff --git a/documentation/projects/planning.md b/documentation/projects/planning.md index 791abc9943b..cc3b2ed7b97 100644 --- a/documentation/projects/planning.md +++ b/documentation/projects/planning.md @@ -42,12 +42,12 @@ For each project, planning documents should be kept in the Refer to the existing projects for reference. ````{tip} -You can initialise a new project using the `just` recipe `init-project`. It +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/init-project 'Project name' 'First IP' 'Second IP' +$ just documentation/create-project 'Project name' 'First IP' 'Second IP' ``` This will create the directory structure for your project with the specified