Feature/make spec update clearer

.github/workflows/build-guidelines.yml

@@ -1,5 +1,4 @@
 name: Build 
-
 on:
   push:
     tags:
@@ -17,25 +16,21 @@ on:
     #     required: false
     #     type: string
     #     default: 'default value'
-
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
-
       - name: Install uv
         run: |
           curl -LsSf https://astral.sh/uv/install.sh | sh
           export PATH="/root/.cargo/bin:$PATH"
           uv --version
-
       - name: Build documentation
         run: |
           mkdir -p build
           ./make.py 2>&1 | tee build/build.log
-
           # Check for a wide range of error indicators in the log
           if grep -q -E "Traceback" build/build.log; then
             echo "::error::Build errors detected in log"
@@ -46,17 +41,31 @@ jobs:
             # Check for the Sphinx temp error file reference and extract it if present
             TEMP_ERROR_FILE=$(grep -o '/tmp/sphinx-err-[^ ]*\.log' build/build.log | head -1)
             if [ ! -z "$TEMP_ERROR_FILE" ] && [ -f "$TEMP_ERROR_FILE" ]; then
-              echo "==== SPHINX DETAILED TRACEBACK START ===="
-              cat "$TEMP_ERROR_FILE"
-              echo "==== SPHINX DETAILED TRACEBACK END ===="
-
               # Save this traceback for artifacts
+              echo "=== TRACEBACK ==="
+              echo "Saving traceback to build/sphinx_traceback.log"
               cp "$TEMP_ERROR_FILE" build/sphinx_traceback.log
             fi
 
+            # Check for FLS differences file reference and extract it if present
+            FLS_DIFF_FILE=$(grep -o '/tmp/fls_diff_[^ ]*\.txt' build/build.log | head -1)
+            if [ ! -z "$FLS_DIFF_FILE" ] && [ -f "$FLS_DIFF_FILE" ]; then
+              # Save this differences file for artifacts
+              echo "=== SPEC LOCK FILE DIFFERENCES ==="
+              echo "Saving spec lock file differences to to build/spec_lock_file_differences.log"
+              cp "$FLS_DIFF_FILE" build/spec_lock_file_differences.txt
+            fi
+
             exit 1
+          else
+            # Even if there's no error, still check for FLS differences file
+            FLS_DIFF_FILE=$(grep -o '/tmp/fls_diff_[^ ]*\.txt' build/build.log | head -1)
+            if [ ! -z "$FLS_DIFF_FILE" ] && [ -f "$FLS_DIFF_FILE" ]; then
+              echo "=== SPEC LOCK FILE DIFFERENCES, NO BUILD ERROR ==="
+              echo "Saving spec lock file differences to to build/spec_lock_file_differences.log"
+              cp "$FLS_DIFF_FILE" build/spec_lock_file_differences.txt
+            fi
           fi
-
       - name: Archive build artifacts
         uses: actions/upload-artifact@v4
         if: always()

README.md

@@ -29,6 +29,52 @@ A machine-parseable artifact will be available at `build/html/needs.json`. (ToDo
 
 A record with checksums of the contents is available at `build/html/guidelines-ids.json`. Users of the coding guidelines can reference this file to determine if there have been changes to coding guidelines contents they should be aware of.
 
+## Build breaking due to out-dated spec lock file
+
+It's a fairly common occurence for the build to break due to an out of date spec lock file, located at:
+
+```
+src/spec.lock
+```
+
+The `spec.lock` is checked against the current live version of the specification, which means that your local development may go out of date while you are developing a feature.
+
+### Continuing work while on a feature branch
+
+If you run into this while developing a feature, you may ignore this error by running the build with:
+
+```shell
+   ./make.py --ignore-spec-lock-diff
+```
+
+### If you need to audit the difference
+
+When the build breaks due to the difference a file is created here:
+
+```
+/tmp/fls_diff_<random>.txt
+```
+
+which can be used to aid in auditing the differences.
+
+Follow the below steps to ensure that the guidelines remain a representation of the FLS:
+
+1. Check if there are any guidelines currently affected, if no, go to 6.
+2. For each affected guideline, audit the previous text and current text of the appropriate paragraph-id in the FLS
+3. If the prior and new text of that paragraph in the FLS does not effect the guideline, proceed back to 2. to the next affected guideline
+4. If the prior and new text of that paragraph do differ in the FLS, then a rationalization step is required
+   1. In the rationalization step, either yourself or another coding guidelines member must modify the guideline to comply with the new text
+5. If you any affected coding guidelines remain proceed back to 2. to the next affected guideline
+6. You are done
+
+Once you have completed the above steps, you will now update the local copy of the `spec.lock` file with the live version:
+
+```shell
+   ./make.py --update-spec-lock-file
+```
+
+Open a new PR with only the changes necessary to rationalize the guidelines with the new FLS text.
+
 ## Contributing to the coding guidelines
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

builder/build_cli.py

@@ -20,7 +20,7 @@
 SPEC_CHECKSUM_URL = "https://spec.ferrocene.dev/paragraph-ids.json"
 SPEC_LOCKFILE = "spec.lock"
 
-def build_docs(root, builder, clear, serve, debug):
+def build_docs(root, builder, clear, serve, debug, spec_lock_consistency_check):
     dest = root / "build"
 
     args = ["-b", builder, "-d", dest / "doctrees"]
@@ -36,6 +36,18 @@ def build_docs(root, builder, clear, serve, debug):
         args += ["-j", "auto"]
     if clear:
         args.append("-E")
+
+    # Initialize an empty list for configuration options (without --define)
+    conf_opt_values = []
+    # Add configuration options as needed
+    if not spec_lock_consistency_check:
+        conf_opt_values.append("enable_spec_lock_consistency=0")
+    # Only add the --define argument if there are options to define
+    if conf_opt_values:
+        args.append("--define")
+        for opt in conf_opt_values:
+            args.append(opt)
+
     if serve:
         for extra_watch_dir in EXTRA_WATCH_DIRS:
             extra_watch_dir = root / extra_watch_dir
@@ -99,6 +111,12 @@ def main(root):
         "-c", "--clear", help="disable incremental builds", action="store_true"
     )
     group = parser.add_mutually_exclusive_group()
+    parser.add_argument(
+        "--ignore-spec-lock-diff",
+        help="ignore fls.lock file differences with live release -- for WIP branches only",
+        default=False,
+        action="store_true"
+    )
     parser.add_argument(
         "--update-spec-lock-file",
         help="update fls.lock file",
@@ -127,6 +145,6 @@ def main(root):
         update_spec_lockfile(SPEC_CHECKSUM_URL, root / "src" / SPEC_LOCKFILE)
 
     rendered = build_docs(
-        root, "xml" if args.xml else "html", args.clear, args.serve, args.debug
+        root, "xml" if args.xml else "html", args.clear, args.serve, args.debug, not args.ignore_spec_lock_diff
     )
 

exts/coding_guidelines/__init__.py

@@ -44,6 +44,9 @@ def setup(app):
     app.add_config_value(name='fls_paragraph_ids_url', 
                          default='https://spec.ferrocene.dev/paragraph-ids.json', 
                          rebuild='env')
+    app.add_config_value(name='enable_spec_lock_consistency',
+                         default=True,
+                         rebuild='env')
 
     app.connect('env-check-consistency', fls_checks.check_fls)
     app.connect('build-finished', write_guidelines_ids.build_finished)