Theory of Operation

This section details how HCM performs it’s tasks.

Component Directory Structure

HCM can create the component directory and place it in your repository. It is commonly placed either at the root of the repository or under the tags directory.

The component directory contains individual directories for each component. Under each individual component name are the releases for that component. Each release directory follows the form of a three dot number: <Major>.<Minor>.<Patch>

The example below shows a component directory with three components: rook, king, and queen.

The rook component has three releases: 1.0.0, 1.1.0, and 2.0.0.

The king component has four releases: 1.0.0, 2.0.0, 2.1.0, and 3.0.0.

The queen component has four releases: 1.0.0, 2.0.0, 2.1.0, and 3.0.0.

components
|
+-- rook
|   |
|   +-- 1.0.0
|   +-- 1.1.0
|   +-- 2.0.0
|
+-- king
|   |
|   +-- 1.0.0
|   +-- 2.0.0
|   +-- 2.1.0
|   +-- 3.0.0
|
+-- queen
    |
    +-- 1.0.0
    +-- 2.0.0
    +-- 2.1.0
    +-- 3.0.0

Differences between releases can be easily determined by comparing the two release URLs.

Repository Considerations

HCM makes several assumptions about the workflow with regards to repositories. The diagram below shows the workflow assuming there are three repositories.

The workflow makes these assumptions:

1. Publishing is restricted to within the local repo.
2. Installing can be performed from either a local or remote repo.

Ownership Considerations

Components should only be developed and published in a single repository. This ensures a single source of truth for the component.

In the diagram above:

• Code in the yellow repository is developed using the yellow working copy.
• Code in the blue repository is developed using the blue working copy.
• Code in the green repository is developed using the green working copy.

You can not develop blue components in the yellow working copy. Revision control tools do not handle crossing repositories well.

HCM configuration file

The HCM configuration file is a JSON file which contains information about the component. There is an HCM configuration file for each component and is updated with every version released.

{
  "name" : "rook",
  "version" : "1.0.0",
  "publish" : {
      "url" : "http://svn/my_repo/components"
  },
  "source" : {
      "url" : "http://svn/my_repo/chess_project/components/rook@1276",
      "manifest" : {
          "rook/rtl/rook.vhd" : "93ffadcc3b73c6292de35564192a99b4",
          "rook/lay/filelist.tcl" : "10019aef04979acfac88673bc5dc6133"
      }
  }
}

The JSON file starts with a single hash key named hcm. This uniquely identifies the information as belonging to HCM. It contains five other keys: url, name, version, source_url, and manifest.

Key	Description
name	name of the component.
version	version of the component that has been published.
publish:url	location of the component directory where this component has been published.
source:url	current URL path and revision where the component was published from.
source:manifest	key value pair of every file that makes up the component. The key is the name of the file relative. The value is an md5sum hash of that file.

The manifest provides a quick method to validate any component to see if anything has changed. It can also assist in transferring components between repos.

Publishing

Publishing uses the svn copy command to take snapshots of a component. The command can only work within a repository.

In the diagram above, you can see all the publish actions take place between a repository and it’s respective working copy.

To publish manually you would follow these steps:

1. Ensure requested component directory exists
2. Validate all files in a component to be published directory are committed.
   1. Any unversioned files must be deleted
   2. it must come back with a clean status
3. Create individual component directory in component directory if it does not exist.
4. Generate the hcm.json file if it does not exist
   1. Read hcm.json file it is does exist
   2. Update version and manifest fields
5. Add hcm.json file to the component directory
6. Commit hcm.json file to working copy
7. svn copy the local component directory to the published directory under the correct version

HCM will validate step 2 has been completed before performing steps 3 through 6.

Installing

Installing can take place from a local repo or a remote repo. If an install is performed from a local repo, then the svn copy command will be used. This provides history between what is installed and what has been published.

If an install is performed from a remote repo, then the svn export command will be used. This pulls the component from the other repo and copies it into the working copy. The files need to be added and then committed. History is not lost in this case, but it is a little more difficult to follow.

Local Install

This is the workflow for a local install:

1. Check if component version exists in repo
2. Check if local component directory is svn status clean
3. Delete component directory in working copy
4. SVN copy component version directory from local repo

HCM will perform all these steps.

Note

Committing the install is the responsibility of the user.

Remote Install

This is the workflow for a remote install:

1. Check if component version exists in repo
2. Check if local component directory is svn status clean
3. Delete component directory in working copy
4. Export component from external repo
5. Add exported component to working copy

HCM will perform all these steps.

Note

Committing the install is the responsibility of the user.

External Install

A component can be installed using an external instead of an svn copy or export. When using an external, the type of repo (external or local) does not matter.

This is the workflow for an external install:

1. Read externals from svn:externals property on current directory
2. Check the status of the local component directory
3. Check if component version exists in repo
4. Update svn:externals property with new component version
5. Update component directory

Uninstalling

Uninstalling removes an installed component. If the component was not an external install, then HCM will just use svn delete to remove the component. If the componet was an external install, then HCM will modify the svn:externals property to remove the component.

In either case, the user is responsible for the final commit to make the uninstall official.

Normal Uninstall

This is the workflow for a normal uninstall:

1. SVN delete component

Note

Committing the uninstall is the responsibility of the user.

External Uninstall

Uninstalling an external requires modifying the svn:externals property of the parent directory.

This is the workflow for an external uninstall:

1. Read externals from svn:externals property on current directory
2. Remove component from svn:externals property
3. Update svn:externals property with new component version
4. Update component directory

Note

Committing the uninstall is the responsibility of the user.

Dependencies

Dependencies between components can be indicated using a file named dependencies.yaml. This file is generated by hand by the user. This is an example dependency file for the rook component:

requires:
  queen:
  king:
  castle:

When rook is installed, HCM will also install queen, king, and castle if they are not already installed.

Install with dependencies

This is the workflow for a local install:

1. Check if component version exists in repo
2. Check if local component directory is svn status clean
3. Delete component directory in working copy
4. SVN copy component version directory from local repo
5. Read dependencies.yaml file
6. Check if components in YAML file have been installed
7. Read dependencies.yaml file for those components that have been installed
8. Install components that have not been installed

This process repeats until all dependencies have been installed. Any duplicate dependencies are ignored. All circular dependencies are broken.

Note

HCM will install the latest version of a component when it is listed as a dependency.

Dependencies file

The HCM Dependencies file is a YAML file listing other components required.

---
requires:
   component1:
   component2:

   componentn:

Each component entry is a key that currently does not have a value. This format was chosen to allow for easy extension of the dependency feature.

This file must be named dependencies.yaml and placed at the root of the component. HCM will search for this file when installing to see if any other components must be installed.

Browsing

Browsing checks the versions of the components available for installation.

The workflow for listing is shown below:

1. Get a listing of all directories in each path in the HCM_URL_PATHS environment variable
2. Get the latest version of each component

The information is then displayed for the user.

Downloading

Downloading can take place from a local repo or a remote repo.

If an install is performed from a remote repo, then the svn export command will be used. This pulls the component from the other repo and copies it into the working copy. The files need to be added and then committed. History is not lost in this case, but it is a little more difficult to follow.

This is the workflow for downloading:

1. Check if component version exists in repo
2. Removing existing download directory if it exists
3. Export component to using component name and version number

Listing

Listing checks the versions of the components currently installed.

The workflow for listing is shown below:

1. Get a listing of all directories
2. Read version from each hcm.json file

The information is then displayed for the user.

Detecting Modifications

Modifications to installed components is important in making several decisions:

1. When to publish
2. Whether to install

This is the workflow for checking is an installed component has modifications:

1. Perform an svn status and check for uncommitted modifications
2. Perform an svn log -R and parse out all the Last Changed Rev values.
3. Extract the Last Changed Rev of the hcm.json file
4. Compare the Last Changed Rev of every file and directory against the hcm.json file
   1. Any file with a rev higher than hcm.json is a committed modified file.

Staging

Note

This is still under development.

Staging is the first step in the Staging-Release method of publishing components. It uses svn diffs to transfer local changes to staging area for inclusion into a future component version. This command will work between repositories.

The following diagram shows the steps necessary to stage a component:

1. Read hcm.json file of component
2. Lock the version directory of the component in the staging repository
3. Perform an svn ls command to get a list of all directories
4. Perform svn checkout of staging version directory with the –depth empty option
5. Create new staging directory to hold staging information
6. Create diff of component and store under new staging directory
7. Update hcm.json file and include staging information
8. Add new staging directory
9. Commit new staging directory
10. Remove staging directory
11. Remove lock.

Note

This is still under development

Merging Staged Updates

Note

This is still under development.

This is the second step in the Staging-Release method of publishing components. At this step, there are one or more updates to an existing version of a component. These updates must be vetted and any desired updates incorporated into a new version.

Given the nature of the effort, this step is entirely manual. HCM can not help at this step.

The following diagram shows the steps necessary to stage a component:

1. ??? Forgot what this step was. I don’t think it was a lock.
2. Check out component that has staged updates
3. Review staged updates and svn add a new version directory based on the updates
4. svn copy the working directory on the current version
5. Apply the first patch to the new working directory and review the results.
6. Apply the successive patches to the new working directory and review the results.
7. Commit final updates to the new version
8. svn delete the stages that were incorporated

Note

This is still under development

Releasing Staged Component

Note

This is still under development.

This is the final step in the Staging-Release method of publishing components. At this step, all updates for a component version have been merged. The component is now ready to be released.

The following diagram shows the steps necessary to stage a component:

1. Check out staged component version to be released.
2. Update hcm.json file
3. Publish component to the new version directory

Note

This is still under development