Seeding the CSAF v2.1 workplace - separating source and deliverables #641
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- created root folder vor CSAF v2.1 - added documentation on the goals as top-level README.md in that folder Signed-off-by: Stefan Hagen <[email protected]>
…tributes - added editor config for ease of collaboration - added git attributes file for cross platform ease - amended git ignores by typical needed artifacts that should stay local Signed-off-by: Stefan Hagen <[email protected]>
- copied all relevant files needed to ease tracing the final v2.1 seed data back to the v2.0 origins - note: everything besides the submit/README.md is unchanged (content wise) and the csaf_2.1/prose/csaf-v2.1-editor-draft.md is a copy of the csaf_2.0/prose/csaf-v2-editor-draft.md file Signed-off-by: Stefan Hagen <[email protected]>
- added a minimal vale config file for spell checks - added a plausible markdownlint config file Signed-off-by: Stefan Hagen <[email protected]>
- to reduce the noise (esp. dealing with the OASIS boilerplate like e.g. frontmatter and the past practice of using bare URLs some exemptions were added to the markdownlint configuration file (still the hack for references triggers a rule we will want to keep, namely blanks-around-headings/blanks-around-headers Signed-off-by: Stefan Hagen <[email protected]>
- cut the elephant markdown file into per level 1 or 2 section sliced files and added a binder file at etc/bind.txt to declare the order for the concatenation - added YAML metadata to the appendix files to ease processing - markdowlint shows the same findings for the elephant and for all source files Sogned-off-by: Stefan Hagen <[email protected]>
…ts, and unspacing - further split of introduction - terminology to obtain a homogeneous definition list file for the glossary part of that section (binder has been updated) - removal of doubled blank lines at the end of segregated source files - the tables in acknowledgements and revision history sections have been fixed to adhere to GFM format and have global per table column widths (both in segregated source files as in the elephant (user facing delivery item in GFM+gh_cosmetics format) - glossary as well as normative and informative references in source are now plain definition lists with URLs correctly wrapped into angle brackets. - no regression tests performed as any regressions can be detected and fixed later, when the transformers (generators for the user facing delivery items) are present and can execute. Signed-off-by: Stefan Hagen <[email protected]>
- removed all volatile section counter displays like '3.1', 'C.1', or 'Appendix A.' from the sources. These can be regenerated from the concat document, using the trigger heading detection post table of contents and the appendix files meta data. - added section mappings from counter display to label and reverse to the etc directory. These files are temporarily used as fall back, but in the subsequent editorial phase will become build time artifacts. - the two non-unique section texts 'Sorting' and 'Vulnerabilities' have been amended with labels that make them unique (and in the context of the latter provide a more descriptive text than the section title itself). Signed-off-by: Stefan Hagen <[email protected]>
- the volatile script for generating the user facing GFM+gh_cosmetics delivery item from the sources (bin/volatile.py) is documented and passes the usual quality controls: + mypy bin/volatile.py (for type verification) + ruff --ignore E501 bin/volatile.py (for general linting) + black -S -l120 bin/volatile.py (single quotes preferred and 120 chars or less long lines format) + vale --config etc/vale.ini bin/volatile.py (developer documentation spell check) - added a share folder with documentation to share the current state of generated GFM+gh_cosmetics format, the user facing delivery item as a single file and as built from current sources within the edit folder - this generated file is not intended to mimic the incoming 'elephant', but instead to enable feedback on the usefulness for end-users reading the current draft of the spec (offering extended navigation capabilities). Signed-off-by: Stefan Hagen <[email protected]>
- removed the <br><br> concat hack from the generator (micro format for another spec) - updated the generated GFM+ user facing delivery item Signed-off-by: Stefan Hagen <[email protected]>
…tion texts - a stray trailing asterisk was removed in the glossary source - when generating the GitHub cosmetics rendering of a definition list we resort to HTML and thus the inner markup like emphasis or strong requires translation into the corresponding HTML elements <em> and <strong> - the volatile tool has been patched up clumsily but still (bin/volatile.py) is documented and passes the usual quality controls: + mypy bin/volatile.py (for type verification) + ruff --ignore E501 bin/volatile.py (for general linting) + black -S -l120 bin/volatile.py (single quotes preferred and 120 chars or less long lines format) + vale --config etc/vale.ini bin/volatile.py (developer documentation spell check) Signed-off-by: Stefan Hagen <[email protected]>
- created real link refs for citations in sources without repetition (only constant tagging per 'cite' text like in [cite](#CWE) instead of the pure display \[[CWE]\] fakes - the links will be rewritten by the modified generator (volatile) and the destination of the links are the entries in the reference sections - the adapted volatile script for generating the user facing GFM+gh_cosmetics delivery item from the sources (bin/volatile.py) is documented and passes the usual quality controls: + mypy bin/volatile.py (for type verification) + ruff --ignore E501 bin/volatile.py (for general linting) + black -S -l120 bin/volatile.py (single quotes preferred and 120 chars or less long lines format) + vale --config etc/vale.ini bin/volatile.py (developer documentation spell check) - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
sthagen
changed the title
sthagen
changed the title
- as a small cosmetic hack, forced all reference entries to be on a single line the line starting with the colon (:) and four spaces to avoid changing the generator for enhancing the look of the rendered sections - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
|
@tschmidtb51 The failing tests appear to be unstable as they fail on the unchanged artifacts in the csaf_v2.0 folder tree ... maybe we should revisit them as this sends the wrong message about change requests ... |
|
@sthagen: Looks like Julian's jsonschema lib changed... I haven't figured out yet whether it is a bug or a feature... |
|
@tschmidtb51 w.r.t. the jsonschema tool, I think it is a feature and I think already migrated in some of my projects. Will take a look. When I find/remember will tell. These GitHub actions I do not like, as you know, they are much too slow and intransparent for my gusto (and time slots I am willing to spend 👴🏽 ...) |
- distributed sentences across lines when reaching the 150 char limit - added a single space between block qupte char (>) and quoted text in one structural element - did NOT fix a reeated 'a a' ;-) - rationale for line length limit and where spotted at lease one line per sentence policy is twofold: (1) avoid horizontal scrolls (2) more semantic diffs in the editorial phase - the examples are in unqualified code blocks (triple backtick fenced)) we should consider specializing as json those that after patching (filling in ellipsis cut markers with valid JSON elements). simeple content examples of field values may best remain untyped - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- fixed directly repeated occurences of 'a', 'for', 'that', and 'the'. - changed 'versioning which compatible wth Semantic' into the correct 'versioning which is compatible with Semantic' - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- replaced volatile with semantic section references (those pointing to our own specification) - found unclear section reference to conformance within conformance - editors should follow up on that one (maybe conformance clause 9 was meant and not section 9) - distributed a few sentences on extra lines that slipped through the initial <150 line sweep - wrapped additional lines that crossed the 150 char limit due to the semantic section references now being active links and thus longer than the volatile simple dotted number strings - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- simplified IETF language URL notation - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- removed trailing space in markdown source of schema-elements-02-properties - frontmatter.md of cours still triggers 14 warnings (3 different rules) but that file is per upstream OASIS and for now out of scope. - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- did split the approx. 1600 lines schema elements properties file on level 3 to further ease editing and reduce conflicts - updated the binder - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- did split the approx. 1150 lines schema elements definitions file on level 3 to further ease editing and reduce conflicts (some files are small but the defs may be worth it) - updated the binder - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- shortened the level three section files of schema definitions and properties - left the level two section files of these to have them up front in listings - updated the binder - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- split the mandatory tests file into section level 2 file and 33 level 3 files to push the maximal line count per file below 800 lines. - the test section level 3 files are in part short, but they have separate concerns (per design) so should work nicely as separate 'modules' - updated the binder - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- add missing tests and examples - update test scripts
- correct spelling mistakes
- addresses parts of oasis-tcs#341 - improve test scripts to use csaf version build folder for strict artifacts
- addresses parts of oasis-tcs#679 - ensure consistent variable naming - add argument -p to suppress error due to existing build folders
- move original GitHub Actions to new folder csaf_2.0 - add `paths` to limit executed actions
- update csaf_2.1/ test files based on oasis-tcs#679
- update aggregator schema from CSAF 2.0 Errata 01
Add tests as GH actions
- remove unnecessary files introduced by merge - remove newline to match csaf_2.0 file
- address forgotten * in terminiology
- temporarily add the mandatory test to make sure the test data is valid
- update aggregator schema - update aggregator examples
- update csaf schema - update csaf examples
- update PMD schema - update PMD example
- update ROLIE example - silently fix incorrect URLs
- update filename test data
- update validator test data - update test script - update testdata schema and list
- update mandatory tests workflow to use preset `mandatory` instead of `basic`
- update validator test data (manual for special situations)
- start editing the first prose files - adopt examples to match prose
- update frontmatter to reflect new version
- change JSON schemas to reflect declared namespace for v2.1
- update rest of prose to use v2.1 - update timestamps for consistency - fix incorrect filesname - adopt test data to reflect changes in prose
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Still not requesting a merge into the baseline, but mirroring the experimental branch of my fork in the main repo on a feature branch with the same name.
Rationale: Make the exploration more visible to encourage a wider feedback.
The user facing "GFM+gh_cosmetics" delivery item
csaf-2.1/prose/csaf-v2.1-editor-draft.md(huge single file online rendition of markdown plus HTML work arounds) can be generated already (the good parts) as is from the source files belowcsaf-2.1/prose/edit/src/with the binder definition incsaf-2.1/prose/edit/etc/bind.txt, and the proof of concept filter atcsaf-2.1/prose/edit/bin/volatile.py.As of commit
20aa5e0this will render like so: https://github.com/oasis-tcs/csaf/blob/20aa5e0/csaf_2.1/prose/share/csaf-v2.1-draft.md.Note that now one can navigate to examples per fragment syntax in 3 different ways:
https://github.com/oasis-tcs/csaf/blob/20aa5e0/csaf_2.1/prose/share/csaf-v2.1-draft.md#usage-of-v-as-version-indicator-eg-1
https://github.com/oasis-tcs/csaf/blob/20aa5e0/csaf_2.1/prose/share/csaf-v2.1-draft.md#sec-6-3-11-eg-1
https://github.com/oasis-tcs/csaf/blob/20aa5e0/csaf_2.1/prose/share/csaf-v2.1-draft.md#example-123
The history of the refactoring can be best traced at (freshest change on top):
The list of commits below this description in the pull request is ordered as freshest change at the bottom ... but otherwise identical (only more scrolling needed to follow).
Identified remaining tasks:
wthinstead ofwith... (vale)Update: The new self-contained single-file HTML file generated from the markdown is currently downloadable at e.g. https://github.com/sthagen/oasis-tcs-csaf/blob/seeding-csaf-v-2-1/csaf_2.1/prose/share/csaf-v2.1-draft.html (or https://git.sr.ht/~sthagen/oasis-tcs-csaf/tree/seeding-csaf-v-2-1/item/csaf_2.1/prose/share/csaf-v2.1-draft.html). The generation is automatic from the generated single-file markdown user facing delivery item (as described per the README file in the prose folder).
Tasks out of scope for this change set: