From ef122eb488ca9c800012ddafd13ca4a1df272564 Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Sat, 7 Mar 2026 13:42:41 +0000 Subject: [PATCH] impoved 00_Project_Structure.html --- .../document/00_Project_Structure.html | 44 ++++++++++++------- shared/{authored => tool}/scratchpad | 0 shared/{authored => tool}/setup | 0 shared/{authored => tool}/style/.gitkeep | 0 shared/{authored => tool}/version | 0 5 files changed, 27 insertions(+), 17 deletions(-) rename shared/{authored => tool}/scratchpad (100%) rename shared/{authored => tool}/setup (100%) rename shared/{authored => tool}/style/.gitkeep (100%) rename shared/{authored => tool}/version (100%) diff --git a/administrator/document/00_Project_Structure.html b/administrator/document/00_Project_Structure.html index 99cf663..2a56aea 100644 --- a/administrator/document/00_Project_Structure.html +++ b/administrator/document/00_Project_Structure.html @@ -40,7 +40,7 @@

- 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: . setup developer, or source setup developer. As of this writing, the supported roles are: administrator, consumer, developer, and tester. + 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.

@@ -48,7 +48,7 @@

-

Key concepts

-

Authored vs. Made

+

Authored, made, scratchpad, third_party, inherited, customizations

- Harmony divides the world into two categories: + 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 separation protects authored material from accidental overwrite and makes build artifacts fully disposable. + 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

@@ -91,12 +101,12 @@
  • shared/ : Shared ecosystem tools and global environments.
    • -

    The administrator work area

    +

    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

    +

    The developer work area

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

    @@ -108,17 +118,17 @@
  • tool/ : Developer-specific tools (like the release and make scripts).
    • -

    The tester work area

    +

    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

    +

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

    @@ -135,7 +145,7 @@
  • Project Release: A project is released when the tester and other team members determine the code in the consumer/release/ directory is fully validated and ready for end users. This is enacted by creating a release branch on the version control system (e.g., GitHub), not by moving files to another directory.
    • -

    Directory names

    +

    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.

    @@ -160,7 +170,7 @@ 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

    +

    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§ diff --git a/shared/authored/scratchpad b/shared/tool/scratchpad similarity index 100% rename from shared/authored/scratchpad rename to shared/tool/scratchpad diff --git a/shared/authored/setup b/shared/tool/setup similarity index 100% rename from shared/authored/setup rename to shared/tool/setup diff --git a/shared/authored/style/.gitkeep b/shared/tool/style/.gitkeep similarity index 100% rename from shared/authored/style/.gitkeep rename to shared/tool/style/.gitkeep diff --git a/shared/authored/version b/shared/tool/version similarity index 100% rename from shared/authored/version rename to shared/tool/version -- 2.20.1