Seeding CSAF v2.1 #680
Merged
Seeding CSAF v2.1 #680
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]>
- 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]>
- 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]>
- the pattern sectionlabel-eg-42 describes the 42nd example in the section with the unique label sectionlabel - this is the path-local example id - the file etc/example-global-to-local.json gives these new path-local ids as values to the CSAF v2.0 OS global example number (both as strings) - the file etc/example-local-to-global.json is the reverse mapping to allow tracing from the future CSAF v2.1 back to the then historic v2.1 Signed-off-by: Stefan Hagen <[email protected]>
- fixed the path-local example ids for tge examples with the version 2.0 global numbers 6 and 7 Signed-off-by: Stefan Hagen <[email protected]>
- replaced all global example numbers with the corresponding path-local (semantic) variants - semantic in so far, as the identifier now containing the section label per position supports guessing on the content. Only 21 of the 143 examples (including the example given as example for examples in the typographical conventions sections have path-local numbers other than 1. - change in pattern: the examples with amending text carry this text now more clearly within parentheses. - two singular example titles have been corrected to plural (where the code block lists more than one example value) - one example description in the v2.0 OS has a twisted sequence of colon (:) and asterisk(*) this has been corrected in the source - there is a single reference to an example by number (global == 4) in the v2.0 OS and by direction stating 'above' that for now has been codified per 'The example [eg](#acknowledgments-type-example-eg-1) above' and for now this is being passed on into the user facing delivery item GFM+ There is a trivial fix changing the content of that 'reference sentence part, rewriting it to 'The example 1 above' which is in the gist of the value only reference found in the v2.0 OS and should just work. This should be discussed by the editors. - In general, when we want to really refer to examples freely with a real link to follow we can simply create an anchor on all examples (which we should do anyway, a label) and then do transforms when generating the resulting deliverables analog to the rewrite we do for citations. - sync'ed the user facing delivery item in share Signed-off-by: Stefan Hagen <[email protected]>
- amended jso as json in example number / identifier maps Signed-off-by: Stefan Hagen <[email protected]>
- experimental: added three kinds of labels to examples: 1. the true path-local label in the section-label-eg-number form 2. the user friendly sec-1-2-3-eg-num form (for example <num> in section 1.2.3) 3. the user firendly global number example-num form - the volatile script has been simply amended with bad but 'what could possibly go wrong' code but even references to non-local examples (from outside of the most fine-grained section containing the referenced example) work, i.e. they transform the link text from 'eg' to 'num (of section1.2.3)' for example number num in section 1.2.3 - before the editorial phase the mostly static logic of reading the maps from etc based JSON files instead of building those structures during the parse of the to be transformed set of sources must be replaced with a dynamic / parsing approach - 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]>
Sync across the forkscape with a merge commit
- added the styles for the HTML user facing delivery item - added documentation on the provenance of these styles - added media folder with original v3.0 OASIS-open logo as well as a dta-url version for constructing self-contained HTML files Signed-off-by: Stefan Hagen <stefan@hagem-link>
- Simple script to enable inlining of PNG fiels (e.g. OASIS logo) for self-contained HTML delivery items Signed-of-by: Stefan Hagen: <[email protected]>
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
Seeding the CSAF v2.1 workplace - separating source and deliverables
- addresses parts of #680 - update citing of CSAF 2.1 - update README with minimum version of tools - regenerated new CSAF drafts in `share` folder
Merged
- update prose example of 6.1.22 to use v2.1 - originally worked on but forgotten to save it
- regenerate Markdown and HTML file
Seeding CSAF 2.1
|
As decided during the TC meeting on 2024-01-31 it will be merged into master. |
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.
@sthagen and @tschmidtb51 prepared a base for the new CSAF 2.1 version. The changes include:
csaf_2.1/prose/sharedirectory)