Following guidance for release testing outputs confusing git errors

[GaryGapinski]

Describe the bug

The suggested method of obtaining a clone of the OSCAL repo at the 1.0.5 release level results in the following:

Example shell output:

gapinski@flexion-mac-C02FCBVSMD6N usnistgov % git clone --recurse-submodules https://github.com/usnistgov/OSCAL.git --branch v1.0.5

Cloning into 'OSCAL'...
remote: Enumerating objects: 118682, done.
remote: Counting objects: 100% (7217/7217), done.
remote: Compressing objects: 100% (749/749), done.
remote: Total 118682 (delta 3722), reused 7106 (delta 3643), pack-reused 111465
Receiving objects: 100% (118682/118682), 354.64 MiB | 10.39 MiB/s, done.
Resolving deltas: 100% (64899/64899), done.
Note: switching to '11809d465c65ebbd8cdfceeaae193219ec5cabee'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

Updating files: 100% (1006/1006), done.
Submodule 'build/metaschema' (https://github.com/usnistgov/metaschema.git) registered for path 'build/metaschema'
Submodule 'docs/themes/uswds' (https://github.com/usnistgov/hugo-uswds.git) registered for path 'docs/themes/uswds'
Cloning into '/Users/gapinski/Projects/github/usnistgov/OSCAL/build/metaschema'...
remote: Enumerating objects: 8468, done.        
remote: Counting objects: 100% (840/840), done.        
remote: Compressing objects: 100% (245/245), done.        
remote: Total 8468 (delta 577), reused 806 (delta 561), pack-reused 7628        
Receiving objects: 100% (8468/8468), 12.64 MiB | 9.35 MiB/s, done.
Resolving deltas: 100% (5239/5239), done.
Cloning into '/Users/gapinski/Projects/github/usnistgov/OSCAL/docs/themes/uswds'...
remote: Enumerating objects: 6202, done.        
remote: Counting objects: 100% (3274/3274), done.        
remote: Compressing objects: 100% (2725/2725), done.        
remote: Total 6202 (delta 399), reused 3230 (delta 377), pack-reused 2928        
Receiving objects: 100% (6202/6202), 11.08 MiB | 9.19 MiB/s, done.
Resolving deltas: 100% (1272/1272), done.
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Total 4 (delta 4), reused 4 (delta 4), pack-reused 0
Unpacking objects: 100% (4/4), 976 bytes | 195.00 KiB/s, done.
From https://github.com/usnistgov/metaschema
 * branch            cbcab49a52a22e1d2ad174f07d93b6394807c71a -> FETCH_HEAD
Submodule path 'build/metaschema': checked out 'cbcab49a52a22e1d2ad174f07d93b6394807c71a'
Submodule 'support/schematron' (https://github.com/usnistgov/schematron.git) registered for path 'build/metaschema/support/schematron'
Submodule 'support/xspec' (https://github.com/xspec/xspec.git) registered for path 'build/metaschema/support/xspec'
Submodule 'website/themes/uswds' (https://github.com/usnistgov/hugo-uswds.git) registered for path 'build/metaschema/website/themes/uswds'
Cloning into '/Users/gapinski/Projects/github/usnistgov/OSCAL/build/metaschema/support/schematron'...
remote: Enumerating objects: 13928, done.        
remote: Total 13928 (delta 0), reused 0 (delta 0), pack-reused 13928        
Receiving objects: 100% (13928/13928), 7.94 MiB | 8.27 MiB/s, done.
Resolving deltas: 100% (11852/11852), done.
Cloning into '/Users/gapinski/Projects/github/usnistgov/OSCAL/build/metaschema/support/xspec'...
remote: Enumerating objects: 18244, done.        
remote: Counting objects: 100% (360/360), done.        
remote: Compressing objects: 100% (182/182), done.        
remote: Total 18244 (delta 214), reused 307 (delta 175), pack-reused 17884        
Receiving objects: 100% (18244/18244), 10.28 MiB | 7.78 MiB/s, done.
Resolving deltas: 100% (13899/13899), done.
Cloning into '/Users/gapinski/Projects/github/usnistgov/OSCAL/build/metaschema/website/themes/uswds'...
remote: Enumerating objects: 6202, done.        
remote: Counting objects: 100% (3274/3274), done.        
remote: Compressing objects: 100% (2725/2725), done.        
remote: Total 6202 (delta 399), reused 3230 (delta 377), pack-reused 2928        
Receiving objects: 100% (6202/6202), 11.08 MiB | 8.01 MiB/s, done.
Resolving deltas: 100% (1272/1272), done.
Submodule path 'build/metaschema/support/schematron': checked out 'e16ecc490f9c6429f275ea268279787a71ff298f'
Submodule 'trunk/schematron/test' (https://github.com/Schematron/schematron-test.git) registered for path 'build/metaschema/support/schematron/trunk/schematron/test'
Cloning into '/Users/gapinski/Projects/github/usnistgov/OSCAL/build/metaschema/support/schematron/trunk/schematron/test'...
remote: Enumerating objects: 88, done.        
remote: Total 88 (delta 0), reused 0 (delta 0), pack-reused 88        
Receiving objects: 100% (88/88), 22.34 KiB | 816.00 KiB/s, done.
Resolving deltas: 100% (38/38), done.
Submodule path 'build/metaschema/support/schematron/trunk/schematron/test': checked out 'b9182deab178f340300d66f806e535369b183da3'
Submodule path 'build/metaschema/support/xspec': checked out 'd8bbeca51eaccc8b3e07c82547f6aff4a2072aef'
Submodule path 'build/metaschema/website/themes/uswds': checked out 'ac7915f3fa4d14fde6115b4a88634f46955a8c20'
Submodule path 'docs/themes/uswds': checked out 'bc74e156ded0936f91aeadcf94447518c567e5a2'
gapinski@flexion-mac-C02FCBVSMD6N usnistgov % git status
fatal: not a git repository (or any of the parent directories): .git
gapinski@flexion-mac-C02FCBVSMD6N usnistgov % cd OSCAL
gapinski@flexion-mac-C02FCBVSMD6N OSCAL % git status
Not currently on any branch.
nothing to commit, working tree clean
gapinski@flexion-mac-C02FCBVSMD6N OSCAL % git --version
git version 2.30.1 (Apple Git-130)
gapinski@flexion-mac-C02FCBVSMD6N OSCAL % 

Goals

• Review release documentation with team and check dispairty between release-1.0.5 branch and corresponding v1.0.5 tag
• If necessary adjust release branch for 1.0.5 (tag should stay the same)
• Make minor editorial update to document checking out release branch instead of tag with git
• Add a second method to check a release by downloading the oscal-.x.y.z.zip file from the releases section as an alternative.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

Who is the bug affecting

Me. Possibly others.

What is affected by this bug

Documentation

How do we replicate this issue

See bug description above.

Expected behavior (i.e. solution)

A git clone which results in the repo at the desired (v1.0.5) branch.

Other comments

git clone --recurse-submodules https://github.com/usnistgov/OSCAL.git --branch release-1.0.5 does not incur an error, nor does git clone --recurse-submodules https://github.com/usnistgov/OSCAL.git --branch release-1.0.5.

Revisions

• A.J. updated original report and added goals and AC

[aj-stein-nist]

It is not on any particular tree, but you are saying that the OSCAL directory is empty? The branch thing is very irritating but that is one of the "fun" fringe benefits of git. Can you run a ls in that directory and tell me what you find?

[GaryGapinski]

The repo from the failed clone contains stuff.

gapinski@flexion-mac-C02FCBVSMD6N usnistgov % cd OSCAL-failed-1.0.5-clone 
gapinski@flexion-mac-C02FCBVSMD6N OSCAL-failed-1.0.5-clone % ls -l
total 408
-rw-r--r--   1 gapinski  staff    3211 Jun 15 11:06 CODE_OF_CONDUCT.md
-rw-r--r--   1 gapinski  staff   16472 Jun 15 11:06 CONTRIBUTING.md
-rw-r--r--   1 gapinski  staff    5255 Jun 15 11:06 LICENSE.md
-rw-r--r--   1 gapinski  staff    5287 Jun 15 11:06 README.md
-rw-r--r--   1 gapinski  staff    8458 Jun 15 11:06 README_validations.md
-rw-r--r--   1 gapinski  staff    1138 Jun 15 11:06 USERS.md
drwxr-xr-x  15 gapinski  staff     480 Jun 15 11:06 build
drwxr-xr-x   5 gapinski  staff     160 Jun 15 11:06 content
drwxr-xr-x   7 gapinski  staff     224 Jun 15 11:06 decisions
drwxr-xr-x  14 gapinski  staff     448 Jun 15 11:06 docs
-rw-r--r--   1 gapinski  staff     609 Jun 15 11:06 git-cheat-sheet.md
drwxr-xr-x   5 gapinski  staff     160 Jun 15 11:06 json
-rw-r--r--   1 gapinski  staff  128540 Jun 15 11:06 slides-2023-02-09.pdf
drwxr-xr-x   9 gapinski  staff     288 Jun 15 11:06 src
-rw-r--r--   1 gapinski  staff    7144 Jun 15 11:06 versioning-and-branching.md
-rw-r--r--   1 gapinski  staff    5699 Jun 15 11:08 x
drwxr-xr-x   5 gapinski  staff     160 Jun 15 11:06 xml
gapinski@flexion-mac-C02FCBVSMD6N OSCAL-failed-1.0.5-clone % git status           
Not currently on any branch.
nothing to commit, working tree clean
gapinski@flexion-mac-C02FCBVSMD6N OSCAL-failed-1.0.5-clone % 

Looks like the v1.0.5 tag — which is not the same as the release-1.0.5 branch — fails during the clone. I had some related confusion here.

[nikitawootten-nist]

The --branch argument of git clone confusingly can point to a branch, tag, or specific commit. The warning about being in a "detached HEAD state" is simply stating that your working directory is not currently "attached" to a branch (it is specifically pointing at a tag).

The repository is still in a functional state, but operations like git pull would not work because you are not attached to a branch. I agree that we should potentially add some commentary on the page explaining how tag checkouts differ from branches.

I also agree that the existence of release branches vs. tagged release commits leads to some additional confusion that should be addressed within the document or the branch structure readme.

[aj-stein-nist]

@nikitawootten-nist maybe we adapt the instructions (since these instructions are the pre-requisite part) and be more explicit with branch checkout?

git clone --recurse-submodules https://github.com/usnistgov/OSCAL.git
git checkout release-1.0.5

Should we move forward with this issue and consider it a request to tweak like that?

[GaryGapinski]

This morning conversation was regarding 1.0.5 testing.

• Those who wish to test a (pre-)release variant (which ages past the point in time it was most recently created) should clone the repo and then checkout the tag (since cloning the tag induces an error).
• Those who wish to test the "live" branch should either clone to a branch or clone then checkout branch.

Or just clone main and checkout branch or tag.

I presume, perhaps wrongly, that the branch is of more interest than the pre-release.