project-chip / project-chip/alchemy

Command descriptions seem to stop at first non-letter character

Open
#19 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
10
Forks
12
Avg merge
23h 54m
Merged PRs (30d)
1

Description

  • Found during running Alchemy against OperationalCredentialsCluster after previously doing manual updates
  • Command: ./alchemy zap --specRoot ~/repos/connectedhomeip-spec-tcv/ --sdkRoot ~/repos/connectedhomeip --verbose ../connectedhomeip-spec-tcv/src/service_device_management/OperationalCredentialCluster.adoc
Actual output

Command descriptions stop at the first non-letter character:

+    <command source="client" code="0x0A" name="RemoveFabric" response="NOCResponse" optional="false">
+      <description>This command is used by Administrators to remove a given Fabric and </description>

However the spec text said:

[[ref_RemoveFabric, RemoveFabric]]
=== RemoveFabric Command
This command is used by Administrators to remove a given Fabric and *delete all associated fabric-scoped data*.

Similarly:

-    <command source="client" code="0x0c" name="SetVIDVerificationStatement" isFabricScoped="true" optional="false" apiMaturity="provisional">
-      <description>This command SHALL be used to update any of the accessing fabric's associated VendorID, VidVerificatioNStatement or VVSC (Vendor Verification Signing Certificate).</description>
+    <command source="client" code="0x0C" name="SetVIDVerificationStatement" isFabricScoped="true" optional="true" apiMaturity="provisional">
+      <description>This command SHALL be used to one or more of the following:</description>

but the spec text said:

This command SHALL be used to one or more of the following:

* Update the VendorID associated with an entry in the Fabrics attribute.
* Associate or remove a <<ref_VIDVerificationStatement,VIDVerificationStatement>> associated with an entry in the Fabrics attribute.
* Associate or remove a <<ref_VendorVerificationSigningCertificate,VendorVerificationSigningCertificate (VVSC)>> associated with an entry in the NOCs attribute.

A similar thing was observed for commands with a <<xref,blahblah>> within the first line, which causes the description to stop before <<.

Expected output:
  • Each command's description should preferably not be truncated. For the multi-bullet descriptions, I am not sure what to do, but a generic description would be better than a truncated description.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue with the shown ./alchemy zap command against OperationalCredentialCluster.adoc, then compare the generated command descriptions with the source text containing punctuation, cross-references, and bullets. Trace the command-description extraction entry point and ensure descriptions are not truncated; verify the result against both examples and decide on a generic description for multi-bullet text.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.