From e7303090f5e118af344921d362f8a3cb05efd3cb Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Sun, 8 Mar 2026 14:40:24 +0000 Subject: [PATCH] 00_Project_Structure --> Introduction to Harmony --- .gitignore | 20 +- LICENSE | 8 +- .../tool => administrator/authored}/.gitkeep | 0 administrator/authored/document/setup.js | 4 + .../document/00_Project_Structure.html | 246 ------------ document/Introduction_to_Harmony.html | 359 ++++++++++++++++++ document/LICENSE | 7 + document/setup.js | 4 + setup | 5 +- shared/authored/.gitkeep | 0 shared/made/.gitkeep | 0 shared/tool/setup | 4 +- 12 files changed, 396 insertions(+), 261 deletions(-) mode change 100644 => 120000 LICENSE rename {developer/tool => administrator/authored}/.gitkeep (100%) create mode 100644 administrator/authored/document/setup.js delete mode 100644 administrator/document/00_Project_Structure.html create mode 100644 document/Introduction_to_Harmony.html create mode 100644 document/LICENSE create mode 100644 document/setup.js create mode 100644 shared/authored/.gitkeep create mode 100644 shared/made/.gitkeep diff --git a/.gitignore b/.gitignore index fcd4eb4..9c8dd19 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,10 @@ +# Protect against accidental local .gitignore deletion +**/scratchpad/* +!**/scratchpad/.gitignore + +# so that .gitignore is not required in consumer/release +/consumer/release + # Python __pycache__/ *.py[cod] @@ -6,9 +13,14 @@ __pycache__/ .ipynb_checkpoints/ .pytest_cache/ -# editor backup files (optional) +# C / compiled artifacts +*.o +*.a +*.out +*.so + +# OS and editor backup files *~ *.bak - -# so that .gitignore is not required in user/release -/user/release +*.swp +.DS_Store diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 51c52bc..0000000 --- a/LICENSE +++ /dev/null @@ -1,7 +0,0 @@ -Copyright © 2019, 2024, 2025, 2026 Reasoning Technology. All Rights Reserved. - -This software, including all source code, compiled code, text, images, graphics, and associated media (collectively, "the Software and Content"), is the proprietary property of Reasoning Technology. - -A limited license, revocable at any time, is granted to access and view the Software and Content strictly for normal web browsing purposes. - -Beyond this limited viewing permission, no other rights are granted. A person is strictly prohibited from copying, extracting, modifying, republishing, distributing, sublicensing, selling, or otherwise exploiting this Software and Content, in whole or in part, for any purpose, without express written consent from Reasoning Technology. No license to any underlying technology, patents, trademarks, or other intellectual property is granted or implied by this access. diff --git a/LICENSE b/LICENSE new file mode 120000 index 0000000..6ba91d5 --- /dev/null +++ b/LICENSE @@ -0,0 +1 @@ +document/LICENSE \ No newline at end of file diff --git a/developer/tool/.gitkeep b/administrator/authored/.gitkeep similarity index 100% rename from developer/tool/.gitkeep rename to administrator/authored/.gitkeep diff --git a/administrator/authored/document/setup.js b/administrator/authored/document/setup.js new file mode 100644 index 0000000..378fdfd --- /dev/null +++ b/administrator/authored/document/setup.js @@ -0,0 +1,4 @@ +window.RT_REPO_ROOT = "../../../"; +document.write(''); +document.write(''); +document.write(''); diff --git a/administrator/document/00_Project_Structure.html b/administrator/document/00_Project_Structure.html deleted file mode 100644 index 2a56aea..0000000 --- a/administrator/document/00_Project_Structure.html +++ /dev/null @@ -1,246 +0,0 @@ - - - - - Project Structure and Ontology - - - - - - - - - - -

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 release workflow.
    3. -
- -

Setup

- -

- Python programmers speak of virtual environment and activate. In contrast, Harmony users speak of roles and setup. Whatever the terminology, this is about setting up the environment by giving values to environment variables. In Python there is one set of environment variable values independent of user role. With Harmony there is a different set of variables depending on the role the user is taking on. -

- -

- A person takes on a role by sourcing the top-level setup script and providing the target role. In a bash shell to take on the role of developer the command is, for example: . setup developer, or source setup developer. As of this writing, the supported roles are: administrator, consumer, developer, and tester. -

- -

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

- - - - -

Documentation

-

Documentation is placed closest to the role it pertains to.

- - -

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. The project tools only read from authored directories. Typically these files constitute the intellectual property of a project. -

-

- Files found in a directory named made were generated by tools in the project. Authors should not edit these files, nor create new files in such a directory, as the directory content is under control of the tools. If a made file requires editing, it is best to find the source of the file, and edit at that point. -

-

- Files found in a directory named scratchpad are not tracked. Hence, a git clone will always return empty scratchpad directories. (Currently this is accomplished by putting a .gitignore file in every scratchpad directory.) 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 can use a scratchpad as a temporary directory for files. There is a tool that comes with the Harmony skeleton with the same name, scratchpad, that is used to maintain scratchpads. Note that one of its commands is clear which deletes everything on a scratchpad. -

-

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

-

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

-

- If an authored file must be added to a project in a location other than an authored directory, it is best to create and edit the file in an authored directory, then to create a symbolic link that points back to it from that other location. -

-

- This approach makes it clear where to find team work product, what is generated by the tools in the project, and what was 'installed' with the project. -

- -

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 shared authored tools, as well as third-party installations (like Python virtual environments or compilers) required by the project. -

- -

The consumer tree

-

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

-

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

- -

Releases

-

- While the workflow document provides a deep dive, it is helpful to understand how directories relate to the concept of a release. There is a distinction between a developer release and a project release. -

- - -

Directory names

-

- Each directory name is a property shared among the files contained within it. Hence, a full path forms a semantic sentence describing each file within it. -

-

- 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. -

-

- When a property name is plural, it describes something about the internal nature of each file. For instance, a directory named constants implies that each individual file inside it (say, physics.py, math.py, and cosmology.py) provides a collection of multiple constants. -

-

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

- - -

- In the Unix file system, a person must choose a single string to use as the directory name. Hence, we typically choose a primary property, though when needed, we use multiple property names separated by an underscore. -

- -

The version 2.2 Harmony directory tree

- - 2026-03-07 10:38:58 Z [Harmony:administrator] Thomas_developer@StanleyPark - §/home/Thomas/subu_data/developer/project§ - > tree Harmony - Harmony - ├── 0pus_Harmony - ├── administrator - │   ├── document - │   │   ├── 00_Project_Structure.html - │   │   ├── 01_Workflow_Build_Contract.html - │   │   ├── Harmony.md - │   │   └── setup.js - │   └── tool - │   ├── after_pull - │   ├── archive - │   ├── release - │   └── 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 - │   │   ├── ontology.org - │   │   └── setup.js - │   ├── experiment - │   ├── made - │   ├── scratchpad - │   └── tool - │   ├── do_all - │   ├── make - │   ├── makefile - │   ├── release - │   └── setup - ├── LICENSE - ├── scratchpad - │   └── Harmony__79f9d52__2026-03-07_085628Z.tar - ├── setup - ├── shared - │   ├── authored - │   │   ├── scratchpad - │   │   ├── setup - │   │   ├── style - │   │   └── version - │   ├── 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 - └── tester - ├── authored - │   └── test_routine.sh - ├── RT_Format - │   ├── RT_Format - │   ├── RT_Format.el - │   ├── test_0_data.c - │   └── test_1_data.py - └── tool - └── setup - - - - - diff --git a/document/Introduction_to_Harmony.html b/document/Introduction_to_Harmony.html new file mode 100644 index 0000000..f46885c --- /dev/null +++ b/document/Introduction_to_Harmony.html @@ -0,0 +1,359 @@ + + + + + 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 release 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. Releases are moved to release branches. +

+ +

Setup

+ +

+ Harmony is language agnostic. When a project makes use of project-specific C, Python, NodeJS, Java, or other tools, the project administrator installs those tools into the shared/third_party directory. The project administrator then modifies the setup files so that paths point to the correct locations and environment variables have the proper values. +

+

+ 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. +

+

+ Because multiple team members and consumers of the work product will have to repeat the third-party install process after cloning a project, the administrator should carefully document the 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/.) +

+

+ 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: +

+ + + +

Directory name

+

+ 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/release directory is maintained by a tool. Said tool is unimaginatively also named release and is found in the developer's tool directory. Hence, documents that are part of a release probably originate from somewhere in the developer/authored directory, perhaps developer/authored/document. +

+ +

+ 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 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. +

+ +

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/release/ tree is where developers put work product that is ready to be consumed. The entire consumer/release directory is git-ignored and treated as a transient deployment target. +

+

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

+ +

Releases

+ +

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

+

+ Then the tester runs tests on the release candidate. Tests must only read from the consumer/release/ 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 release candidate, run the tests, edit source code, and perhaps tests, and then quickly spin through the test-debug-fix-release 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. +

+ +

Modifying the setup

+ +

+ For project wide setup modifications create or edit shared/authored/setup. Note that the shared/authored/setup file is sourced after the inherited shared/tool/setup file, and before the <role>/tool/setup file. +

+ +

+ For role specific setup modifications edit the appropriate <role>/tool/setup file. +

+

+ If these approaches are not sufficient, then edit the setup scripts directly. Note however, that such changes + will appear when the Harmony sync tool is run. +

+ +

The version 2.2 Harmony directory tree

+ + + 2026-03-07 14:50:50 Z [Harmony:administrator] Thomas_PM@ManhattanSquare + §/home/Thomas/subu_data/PM/project§ + > tree Harmony + Harmony + ├── 0pus_Harmony + ├── administrator + │   ├── authored + │   ├── document + │   │   ├── 00_Project_Structure.html + + + │   │   ├── 01_Workflow_Build_Contract.html + │   │   ├── Harmony.md + │   │   └── setup.js + │   └── tool + │   ├── after_pull + │   ├── archive + │   ├── release + │   └── 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 + │   │   ├── ontology.org + │   │   └── setup.js + │   ├── experiment + │   ├── made + │   ├── scratchpad + │   └── tool + │   ├── do_all + │   ├── make + + + │   ├── makefile + │   ├── release + │   └── setup + ├── LICENSE + ├── scratchpad + │   └── Harmony__79f9d52__2026-03-07_085628Z.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 + + 29 directories, 37 files + + + + + diff --git a/document/LICENSE b/document/LICENSE new file mode 100644 index 0000000..51c52bc --- /dev/null +++ b/document/LICENSE @@ -0,0 +1,7 @@ +Copyright © 2019, 2024, 2025, 2026 Reasoning Technology. All Rights Reserved. + +This software, including all source code, compiled code, text, images, graphics, and associated media (collectively, "the Software and Content"), is the proprietary property of Reasoning Technology. + +A limited license, revocable at any time, is granted to access and view the Software and Content strictly for normal web browsing purposes. + +Beyond this limited viewing permission, no other rights are granted. A person is strictly prohibited from copying, extracting, modifying, republishing, distributing, sublicensing, selling, or otherwise exploiting this Software and Content, in whole or in part, for any purpose, without express written consent from Reasoning Technology. No license to any underlying technology, patents, trademarks, or other intellectual property is granted or implied by this access. diff --git a/document/setup.js b/document/setup.js new file mode 100644 index 0000000..ca24761 --- /dev/null +++ b/document/setup.js @@ -0,0 +1,4 @@ +window.RT_REPO_ROOT = "../"; +document.write(''); +document.write(''); +document.write(''); diff --git a/setup b/setup index 2072dfd..4680dc0 100644 --- a/setup +++ b/setup @@ -36,7 +36,10 @@ fi # setup the project # - source shared/authored/setup + source shared/tool/setup + if [[ -f "shared/authored/setup" ]]; then + source shared/authored/setup + fi # setup tools # diff --git a/shared/authored/.gitkeep b/shared/authored/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/shared/made/.gitkeep b/shared/made/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/shared/tool/setup b/shared/tool/setup index 2284ba2..a461f9a 100644 --- a/shared/tool/setup +++ b/shared/tool/setup @@ -47,11 +47,9 @@ unset PYTHONHOME # PATH # precedence: last defined, first discovered - PATH="$REPO_HOME/shared/third_party/RT-project-share/release/bash:$PATH" - PATH="$REPO_HOME/shared/third_party/RT-project-share/release/amd64:$PATH" - PATH="$REPO_HOME/shared/third_party:$PATH" PATH="$REPO_HOME/shared/authored:$PATH" PATH="$REPO_HOME/shared/made:$PATH" + PATH="$REPO_HOME/shared/tool:$PATH" # Remove duplicates clean_path() { -- 2.20.1