Mercurial > p > roundup > code
changeset 8064:d6b447de4f59
docs: set up for release documentation.
Make changes to publish security.html with CVE announcements referring
to the sections in upgrading.html rather than CVE.html.
Remove templates.zip as part of html build in Makefile.
Also update doc for using CVE.html.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Tue, 09 Jul 2024 09:34:13 -0400 |
| parents | 6d4b5005abf2 |
| children | e44b65651012 |
| files | doc/CVE.txt doc/upgrading.txt website/www/Makefile website/www/conf.py website/www/contents.txt |
| diffstat | 5 files changed, 29 insertions(+), 21 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/CVE.txt Tue Jul 09 09:12:29 2024 -0400 +++ b/doc/CVE.txt Tue Jul 09 09:34:13 2024 -0400 @@ -2,21 +2,26 @@ This file is a temporary way to post CVE notifications before a release. - Document the CVE fix info in upgrading.txt. Publishing - upgrading.txt would push info on the next release not the current - release. + Document the CVE fix info in upgrading.txt. We extract the sections + from upgrading.txt that deal with the CVE into a separate CVE.html. + An updated docs/security.html and docs/CVE.html provide the details + on a between release CVE announcment. + + Publishing upgrading.txt would include info on the to be released + roundup software and wouldn't match the rest of the release docs. - So we comment out a reference anchor in upgrading.txt and use that - comment to extract the section from upgrading.txt into CVE.txt. - The extracted section gets the same anchor that is in upgrading.txt, - but is is not commented out. + To extract the info from upgrading.txt to use in CVE.html, add a + commented out a reference anchor in upgrading.txt. Then in CVE.txt + we use an include directive with start-after and end-before options + to exract the sections from upgrading.txt into CVE.html. - Then we add a summary to the list of CVE's in security.txt using a - :ref: to the anchor. If CVE.txt is part of the build and - upgrading.txt has a commented out anchor, security.txt entries link - to CVE.html in the generated documentation. + The extracted section in CVE.txt gets the same anchor that is in + upgrading.txt, but is is not commented out. This allows us to swap + out CVE.txt and uncomment the reference in upgrading.txt. Then + rerunning sphinx-build will make security.html point to the sections + in upgrading.html. - In upgrading.txt add a + For example, in upgrading.txt add a .. comment: _CVE-2024-39124: @@ -44,14 +49,17 @@ :end-before: .. comment: end of CVE After building the docs, install docs/security.html and - docs/CVE.html on the web site. Use the security.html URL - on the web site to update the CVE report. + docs/CVE.html on the web site. Reference: + + https://www.roundup-tracker.org/docs/security.html + + in the CVE announcement from Mitre. When the release is ready, replace 'comment: _CVE' with '_CVE' in upgrading.txt. This makes the anchors in upgrading.txt live. - Then disable CVE.txt by removing CVE.txt from contents.txt in the - toctree hidden section. Also add CVE.txt to exclude_patterns in + Then disable CVE.txt by removing CVE.txt from contents.txt in the + toctree hidden section. Also add docs/CVE.txt to exclude_patterns in conf.py. No change needs to happen to security.txt as it's using a :ref: and
--- a/doc/upgrading.txt Tue Jul 09 09:12:29 2024 -0400 +++ b/doc/upgrading.txt Tue Jul 09 09:34:13 2024 -0400 @@ -122,7 +122,7 @@ Also if you have ``html_version`` set to ``xhtml``, you will get an error. -.. comment: _CVE-2024-39124: +.. _CVE-2024-39124: Fix for CVE-2024-39124 in help/calendar popups (recommended) ------------------------------------------------------------ @@ -314,7 +314,7 @@ This section is for people who can not upgrade yet, and want to fix the issues. -.. comment: _CVE-2024-39125: +.. _CVE-2024-39125: Referer value not escaped CVE-2024-39125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -342,7 +342,7 @@ This escapes the Referer value an prevents it from being executed. -.. comment: _CVE-2024-39126: +.. _CVE-2024-39126: Stop JavaScript execution from attached files CVE-2024-39126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--- a/website/www/Makefile Tue Jul 09 09:12:29 2024 -0400 +++ b/website/www/Makefile Tue Jul 09 09:34:13 2024 -0400 @@ -24,7 +24,7 @@ # after upgrade to sphinx 1.8.5, search.html is missing load of searchtools. # fix that in postprocess # also sed index.html to properly format meta og:... entries. -html: docs templates.zip +html: docs rm -rf html mkdir -p $(TMP)/doctrees $(HTML) sphinx-build -n -W -b html -d $(TMP)/doctrees . $(HTML)