From 7dc3f082563a25d172582a2b0678d02a67fb262f Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Tue, 10 Mar 2026 08:02:07 +0000 Subject: [PATCH] how to do a release docs --- README.md | 14 +- administrator/document/Release_howto.html | 101 +++++ document/Intro.html | 394 ------------------ ...oduct-development_roles-and-workflow.html} | 0 ...roduct-maintenance_roles-and-workflow.html | 100 +++++ document/temp.html | 91 ++++ 6 files changed, 304 insertions(+), 396 deletions(-) create mode 100644 administrator/document/Release_howto.html delete mode 100644 document/Intro.html rename document/{Product_Development_Roles_and_Workflow.html => Product-development_roles-and-workflow.html} (100%) create mode 100644 document/Product-maintenance_roles-and-workflow.html create mode 100644 document/temp.html diff --git a/README.md b/README.md index dc02733..162eeaa 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,20 @@ To create a Harmony-based project, the project administrator performs these step ## Viewing the Documentation -To view the project documentation with its intended formatting, a person must provide the RT style library. It is recommended to clone the styling repository side-by-side with your new project directory, and then link it into the third-party directory. +To view the project documentation with its intended formatting, a person must provide the RT style library. One way to do this is to clone the styling repository side-by-side with your new project directory, and then to link it into the third-party directory. -From the root of your new project repository, run: +From the parent directory of your new project, clone the required style repository: + +```bash +cd .. +git clone -b release_v1 https://github.com/Thomas-Walker-Lynch/RT-style-JS_public +``` + +Then, from the root of your new project repository, link it: ```bash cd shared/third_party ln -s ../../../RT-style-JS_public RT-style-JS_public +``` + +Find an introductory document at `document/Introduction_to_Harmony.html'. After the style library is installed, clicking on it in file navigator should open it in a browser. diff --git a/administrator/document/Release_howto.html b/administrator/document/Release_howto.html new file mode 100644 index 0000000..888d414 --- /dev/null +++ b/administrator/document/Release_howto.html @@ -0,0 +1,101 @@ + + + + + Release howto + + + + + + + + + + +

Prerequisites

+

+ A release requires a tested promotion candidate. The developer compiles the code and promotes it to the consumer/made directory. The tester validates the candidate. The product manager gives the order to release. +

+ +

Create the release branch

+

+ The administrator executes the release. Open a terminal. Enter the project workspace. +

+ + > . setup administrator + + +

+ Switch to the core development branch. Ensure the local repository is current. +

+ + > git checkout core_developer_branch + > git pull + + +

+ Create a new branch for the release. Use the major version number. +

+ + > git checkout -b release_v<major> + + +

Issue management and patching

+

+ Only critical issues receive patches on a release branch. The product manager defines what is critical. If approved, the release team applies the fix directly to the existing release_v<major> branch. +

+

+ The branch name release_v<major> remains static. The code on the branch is updated. The administrator advances the minor release number in the shared/tool/version file. +

+

+ The administrator tags the new commit with the full version number, such as v<major>.<minor>. Minor versions are edits on the major release branch. They are visible to a person by running the version command. +

+

+ The developer must ensure the fix is also ported to the core_developer_branch. This prevents the defect from reappearing in future major releases. +

+ +

Tag and push

+

+ Tag the release with the exact version number. +

+ + > git tag -a v<major>.<minor> -m "Release v<major>.<minor>" + + +

+ Push the branch to the remote repository. Push the tags. +

+ + > git push origin release_v<major> + > git push origin --tags + + +

Repository default branch

+

+ Set the repository default branch to the new release_v<major> branch on the hosting platform. This ensures a person cloning or pulling the repository receives the most recent major release code by default. +

+ +

Verification

+

+ Check the remote repository. Confirm the branch exists. Confirm the tag is visible. Confirm the default branch is updated. +

+ +

Role responsibilities

+ + + + + diff --git a/document/Intro.html b/document/Intro.html deleted file mode 100644 index 6852689..0000000 --- a/document/Intro.html +++ /dev/null @@ -1,394 +0,0 @@ - - - - - Introduction to Harmony - - - - - - - - - - -

Purpose

-

- Harmony provides a language-agnostic project directory structure and maintenance tools for long-lived, multi-person team software development. The structure exists to enforce: -

-
    -
  1. Clarity about where things live. -
      -
    • Role-based work areas.
      • -
    • Separation of skeleton, team member authored, machine-made, and third-party installed software.
      • -
    -
    2. -
  2. A safe, predictable build and promotion workflow.
    3. -
- -

- Harmony is a project skeleton, a set of tools and directories that have been checked into a git repository. To create a Harmony-based project, the project administrator performs these steps: -

-
    -
  1. Clone the Harmony project to a local directory.
    2. -
  2. Remove the .git tree.
    3. -
  3. Rename the Harmony directory to the name of the new project.
    4. -
  4. Rename the 0pus_Harmony file to reflect the name of the new project.
    5. -
  5. Add a line to the shared/tool/version file for the new project.
    6. -
  6. git init -b core_developer_branch
    7. -
- -

- The order is important so as to protect the Harmony skeleton project from accidental check-ins from users. -

-

- Leave the Harmony skeleton version in the version file, so that project administrators can understand what has changed in the skeleton over time. -

-

- The core_developer_branch is the branch that the core development team works on. Project releases are moved to release branches. -

- -

Environment Setup

-

- Python programmers who use virtual environments will be familiar with an analogous process. The term 'virtual environment' does not invoke any hardware virtualization features; rather, it is a local environment setup. To avoid confusion, a Harmony user refers instead to the 'project setup'. The command to establish the environment is called 'setup' instead of 'activate'. Also note that in Harmony, unlike in Python, there are multiple setups available, each tailored to the specific role a person takes on. -

-

- As of the time of this writing, the defined roles are: administrator, consumer, developer, and tester. A person takes on a role by sourcing the top-level setup script and giving the target role as an argument. For example, in a bash shell with > as the prompt, the command is: -

- - - > . setup <role> - - -

- Specifically for the developer role: -

- - - > . setup developer - - -

- For the administrator role: -

- - - > . setup administrator - - -

- Instead of starting with a period, the source command can be spelled out explicitly, for example: -

- - - > source setup tester - - -

- Behind the scenes, the setup script performs the following actions: -

- - - -

After git clone

-

- Because git does not track certain directories (such as shared/third_party/ and consumer/made/), a freshly cloned repository lacks external dependencies and consumable products. Team members must perform a few steps to populate these areas. -

- -

Third-party tools

-

- Harmony is language agnostic. When a project makes use of project-specific C, Python, NodeJS, Java, or other tools, the project administrator configures the project to expect these tools in the shared/third_party directory. -

-

- Because multiple team members will have to repeat the third-party install process after cloning a project, the administrator should carefully document the third party tools installation steps and place the resulting documents in the shared/document directory. (The most common installation method is to clone the third party tool next to the project, then to symbolic link it under shared/third_party/.) -

-

- If a person clones the project and does not set up third-party tools, commands will fall through the search path and perhaps find system-installed tools. Using system default tools is generally undesirable because each person who clones the project might be running different versions. This variation makes it harder for team members to coordinate and for consumers of the project work product to build functioning tools. -

- -

Consumer build

-

- In this section we use the term 'consumer' to mean any team member that wants to make use of the project work product. The tester will want to test it, and the consumer role will want to deploy it, etc. -

-

- An earlier version of Harmony used platform-specific made directories, but this left binaries in the repository and added excessive complexity. - So as to avoid that mess, the current version of Harmony requires a work product consumer to run a local build after cloning the project. The results of the build will appear in the consumer/made directory. -

-

- To facilitate this, the developer must explicitly document the project's build and promote procedure, saving this guide as developer/document/build.html. -

-

- The consumer must then read this document and execute the described steps to compile the source and locally populate the consumer/made directory. -

- -

- Typically the consumer build procedure will be a variation of the following: -

- -
    -
  1. bash
    2. -
  2. > cd
    3. -
  3. > . developer
    4. -
  4. > make CLI
    5. -
  5. > promote write
    6. -
  6. > exit
    7. -
  7. bash
    8. -
  8. > cd
    9. -
  9. > .
    10. -
- -

This opens a bash shell for the build, makes the work product, then promotes it to the consumer's workspace. The last two lines put the consumer into role specific workspace. From there the tester can start testing, and the consumer role can work on deployment. (Commonly deployment is a matter of adding the consumer/made directory into the executable search path.) -

- -

Directory name

-

- This section is discusses our thinking in naming the files and directories found in the Harmony skeleton. -

-

- A directory name is considered to be a property given to each file contained in the directory. A full path then forms a semantic sentence describing each file. -

-

- Because a directory name represents a property, it is rarely plural. For example, when each and every file in a directory is a test, the directory is named test. -

-

- We run into limitations when using a conventional file system as though it were a property based file system. One limitation is that we are forced to choose a single directory name for each file. When a set of files in a directory all share the same multiple properties, we can use a compound directory name with the properties separated by an underscore, but it is impractical to specify overlapping directory groupings, i.e. we can't arbitrarily define any number of properties for a file in this manner. We will see later how this affects Harmony when discussing authored files. -

-

- The following list presents each property type in order of preference when naming directories. -

- - -

Document directories

-

- There is a directory for documents that talks about the project as a whole, one for each role, one for tools that are shared among the roles, and the released work product probably comes with a document directory of its own. -

- - -

- Note that the consumer/made directory is untracked by git and maintained by a tool. (Said tool is developer/tool/promote. It is owned and used by the developer as part of the build process.) Documents that are being promoted for eventual release, and appear in the made directory originate from somewhere from the developer/authored directory depending on how the developer has organized his workspace, but probably in developer/authored/document. Perhaps a future version of Harmony will have a tech-writer role, but that is not the case now. -

- -

- Currently, our developers write documents directly in HTML using the RT semantic tags. See the RT-style-JS_public project and the documentation there. A common approach is to copy another document and the setup.js file, then to type over the top of that other document. Only one setup.js file is used per directory. Be sure to edit the relative root path found at the top of setup.js. Plain text, emacs org, and mark down have all been used in prior versions of Harmony. -

- - -

Authored, made, scratchpad, third_party, inherited, customizations

- -

- Files found in a directory named authored were written by project team members. They did not come with the Harmony skeleton, nor with the installation of other software. Project build tools treat authored directories as strictly read-only. Typically these files constitute the intellectual property of a project. -

- -

- All source code that gets built into a promotion or project release must be placed in the developers' authored directory. The story is not as clean for build tools and other files. New documents go into document directories, and new tools go into the tool directories, etc. As a specific example, the developer will almost certainly edit the developer/tool/make file. -

- -

- When the Harmony version line in the shared/tool/version file is left in place, it is straightforward for a project administrator to determine which Harmony skeleton files have been edited in a project, and which new files have been added. -

- -

- [As a historical note, in the first version of Harmony a directory or file was marked as authored by adding a pencil suffix, '🖉'. Tools then respected this, for example by refusing to delete such files. However, this ad hoc approach to properties was awkward, and people had difficulty typing the marker. When the pencils were dropped, a number of authored files, such as an edited developer/tool/make🖉 file, were no longer explicitly marked as authored.] -

- -

- Files found in a directory named scratchpad are not tracked. Hence, a git clone will always return empty scratchpad directories. It is common for tools to place intermediate files on a scratchpad. It is also common for files to be staged on a scratchpad. Tools play nice and use subdirectories on the pad, so a person who is aware of those subdirectory names can use a scratchpad as a temporary directory. There is a scratchpad maintenance tool that comes with the Harmony, called unimaginatively, scratchpad. Pay attention as one of its commands is clear, and that deletes everything on the current directory's scratchpad. -

- -

- Third party software is installed under shared/third_party. -

- -

- Other files are said to be inherited, or to be customizations. -

- -

Untracked directories

-
    -
  1. consumer/made/
    2. -
  2. shared/third_party/
    3. -
  3. **/scratchpad/
    4. -
- -

Top-level repository layout

-

- A team member will source the project setup file to take on a role. As of this writing, the supported roles are: administrator, developer, tester, and consumer. -

- - - -

The administrator work area

-

- This directory holds the tools and documentation used to manage the project as a whole. It includes the HTML documentation for the project ontology and workflow, as well as project-local tools utilized by the administrator to maintain the Harmony skeleton. -

- -

The developer work area

-

- This directory is entered by first going to the top-level directory of the project, then sourcing . setup developer. -

- - -

The tester work area

-

- This directory is dedicated to formal testing, including regression suites. While a developer can run and keep informal spot tests in their experiment/ directory, any experiment promoted to a formal test is moved here. This enforces the boundary between writing code and validating it. -

- -

The shared tree

-

- This directory contains ecosystem tools and global environments available to all roles. This includes the shared tool directory, as well as third-party installations (like Python virtual environments or compilers) required by the project. To assist in project specific modifications to the Harmony skeleton, Harmony comes with an empty shared/authored directory that is listed earlier in the executable search path than shared/tool. -

- -

The consumer tree

-

- The consumer/made/ tree is where developers put work product that is ready to be consumed. The entire consumer/made directory is git-ignored and treated as a transient deployment target. -

-

- Artifacts arrive in the consumer/made/ tree only when the developer invokes the promote script, which performs a flat-copy from the developer's scratchpad/made directory. -

- -

Workflow

- -

See the document "Product Development Roles and Workflow" for more details.

- -

Developer promotion and project releases

- -

- As a first step, a developer creates a promotion candidate inside of the consumer/made/ directory. This is typically done by running make to stage the artifacts into scratchpad/made, where they can be experimented on, followed by running promote write. The developer will often modify the versions of one or both of those tools that come with the Harmony skeleton. The promotion candidate remains stable until the next promotion. -

-

- Then the tester runs tests on the promotion candidate. Tests must only read from the consumer/made/ directory, though local copies can be made and edited as experiments. Currently bugs are filed using an external issues tool. -

-

- It is common for a developer to open a second window on his desktop, and then enter the project as a tester in that second window. The developer can then make a promotion candidate, run the tests, edit source code, and perhaps tests, and then quickly spin through the test-debug-fix-promote cycle repeatedly. -

-

- When the product manager determines the work product to be sufficiently reliable and feature rich, the administrator will make a project release. He will do this by creating a branch called release_v<major> and tagging it. The major release numbers go up incrementally. -

- -

The version 2.2 Harmony directory tree

- - - 2026-03-09 01:42:16 Z [Harmony:administrator] Thomas_developer@StanleyPark - §/home/Thomas/subu_data/developer/project§ - > tree Harmony - Harmony - ├── 0pus_Harmony - ├── administrator - │ ├── authored - │ ├── document - │ │ └── setup.js - │ └── tool - │ ├── archive - │ └── setup - ├── consumer - │ ├── scratchpad - │ └── tool - │ └── env - ├── developer - │ ├── authored - │ │ └── hello.cli.c - - - │ ├── document - │ │ ├── 02_RT_Code_Format.html - │ │ ├── 03_Naming_and_Directory_Conventions.html - │ │ ├── 04_Language_Addenda.html - │ │ └── setup.js - │ ├── experiment - │ ├── made - │ ├── scratchpad - │ └── tool - │ ├── do_all - │ ├── make - │ ├── makefile - │ ├── promote - │ └── setup - ├── document - │ ├── Introduction_to_Harmony.html - │ ├── Product_Development_Roles_and_Workflow.html - │ └── setup.js - ├── LICENSE - - - ├── README.md - ├── scratchpad - │ ├── Harmony__79f9d52__2026-03-07_085628Z.tar - │ └── Harmony__e665bb7__2026-03-09_013712Z.tar - ├── setup - ├── shared - │ ├── authored - │ ├── document - │ │ ├── install_generic.org - │ │ ├── install_Python.org - │ │ └── setup.js - │ ├── made - │ ├── style_directory_dict.js - │ ├── third_party - │ │ ├── RT-style-JS_public -> ../../../RT-style-JS_public/ - │ │ └── upstream - │ └── tool - │ ├── scratchpad - │ ├── setup - - - │ ├── style - │ └── version - └── tester - ├── authored - │ └── test_routine.sh - ├── RT_Format - │ ├── RT_Format - │ ├── RT_Format.el - │ ├── test_0_data.c - │ └── test_1_data.py - └── tool - └── setup - - 30 directories, 36 files - - 2026-03-09 01:42:19 Z [Harmony:administrator] Thomas_developer@StanleyPark - §/home/Thomas/subu_data/developer/project§ - > - - - - - diff --git a/document/Product_Development_Roles_and_Workflow.html b/document/Product-development_roles-and-workflow.html similarity index 100% rename from document/Product_Development_Roles_and_Workflow.html rename to document/Product-development_roles-and-workflow.html diff --git a/document/Product-maintenance_roles-and-workflow.html b/document/Product-maintenance_roles-and-workflow.html new file mode 100644 index 0000000..6063077 --- /dev/null +++ b/document/Product-maintenance_roles-and-workflow.html @@ -0,0 +1,100 @@ + + + + + Product maintenance roles and workflow + + + + + + + + + + +

Maintenance philosophy

+

+ Deployed software must be a usable quality product for the customer, beyond that we favor addressing issues in new releases, and encourage customers who are having issues to upgrade. This approach is purely one of keeping the maintenance problem tractable. +

+ +

Maintenance structure

+

+ Teams mentioned in this document: +

+
    +
  1. tester team
    2. +
  2. core developer team
    3. +
  3. branch maintenance team
    4. +
  4. triage team
    5. +
+ +

+ Team membership is a role a person takes on. Multiple people can share a single role, and one person might take on multiple roles. +

+ +

+ The tester team develops and maintains the regression suite, the reliability suite, and additional tests. +

+ +

+ The core developer team writes the source code and compiles promotion candidates. +

+ +

+ The branch maintenance team is typically a subset of the core developer team. This group is dedicated to applying approved fixes to specific release branches. +

+ +

+ The triage team evaluates defects reported against active releases. The team usually includes a developer contact, the project manager, and the product manager. +

+ +

Issue queues

+

+ The project maintains two primary issue queues: +

+
    +
  1. released product
    2. +
  2. core developer
    3. +
+ +

+ There can be additional queues for multiple branches of development, and for experiments. +

+ +

Core developer queue

+

+ This queue serves the core_developer_branch. A tester writes a test for every issue reported in this queue. Doing so isolates the defect, proves the fix, and guards against future regressions. +

+ +

Released product queue

+

+ All issues found in release branches go onto this queue initially. It tracks defects reported against deployed software across any major version. +

+ +

Triage and patching

+

+ Guided by the project philosophy, the triage team reviews each release queue issue to determine its impact. The team assesses whether the defect affects the core_developer_branch, assuming by default that it probably does. The team also determines if the defect is critical enough to warrant a patch on one or more active release branches. +

+

+ Based on this assessment, the triage team files actionable tickets in the core developer queue. A ticket explicitly specifies its target branches. A ticket will be filed against either the core developer branch, specific release branches, or a combination of both. +

+

+ Members of the tester team also file tickets directly into the core developer queue when they discover defects in the core branch. +

+

+ Responsibility for resolving a ticket depends on its target. The core developer team addresses fixes required on the core_developer_branch. The branch maintenance team addresses fixes required on the release_v<major> branches. +

+

+ When a release is patched, the branch name remains static. The administrator advances the minor release number in the shared/tool/version file and tags the commit. +

+ + + + diff --git a/document/temp.html b/document/temp.html new file mode 100644 index 0000000..ac7bd7a --- /dev/null +++ b/document/temp.html @@ -0,0 +1,91 @@ + + + + + + Product maintenance roles and workflow + + + + + + + + + + +

Maintenance structure

+

+ Teams mentioned in this document: +

+
    +
  1. tester team
    2. +
  2. core developer team
    3. +
  3. triage team
    4. +
+ +

+ Team membership is a role a person takes on. Multiple people share a role. A single person takes on multiple roles. +

+ +

+ The tester team develops and maintains the regression suite, the reliability suite, and additional tests. +

+ +

+ The developer team writes the source code, compiles promotion candidates, and ports patches between branches. +

+ +

+ The triage team evaluates defects reported against active releases. The team includes a developer contact, the project manager, and the product manager. +

+ +

Issue queues

+

+ The project maintains two distinct issue queues: +

+
    +
  1. released product
    2. +
  2. core development
    3. +
+ +

+ There can be additional queues for multiple branches of development, and for experiments. +

+ +

Core development queue

+

+ This queue serves the core_developer_branch. The tester writes a test for every issue reported in this queue. This isolates the defect, proves the fix, and guards against future regressions. +

+ +

Released product queue

+

+ This queue tracks defects reported against deployed software across any major version. +

+

+ Deployed software must be a usable quality product for the customer, beyond that we favor addressing issues in new releases, and encourage customers who are having issues to upgrade. This approach is purely one of keeping the maintenance problem under control. Other business units should address the commercial implications. +

+

+ Thus the triage team reviews each release issue. All issues that affect the core_developer branch are placed on the core development queue. Critical issues are also placed on the released product queue. The core development team is responsible for the core development queue issues, while the triage component of the development team is responsible for the released product queue issues. +

+ +

Patching and backporting

+

+ The product manager defines what constitutes a critical issue. Only critical issues receive patches on a release branch. +

+

+ If approved, the release team applies the fix directly to the existing release_v<major> branch. The branch name remains static. The administrator advances the minor release number and tags the commit. +

+

+ The developer then ports the fix to the core_developer_branch. This step is mandatory. It prevents the defect from resurrecting in future major releases. +

+ + + + -- 2.20.1