Should we publish other OpenSSF materials like the Concise Guides (aka "Simplest Possible Process")?

[david-a-wheeler]

We currently publish most of the OpenSSF results as links to the GitHub source repo. The Best Practices WG is now using a different approach to publishing a few pages using GitHub pages and a subdomain. I'll call this new-to-OpenSSF approach the "Simplest Possible Process" (SPP). Should we (the OpenSSF) use the SPP for publishing other works? Or should we use a different process?

The current approach we use for distributing most of our results has many problems. The current approach shows readers lots of irrelevant text (the GitHub source repo interface), we cannot control its formatting, the URLs aren't related to the openssf.org domain, most metadata (such as the description) is wrong, and search engines are likely to give it low scores (because it's "just a random page on GitHub"). For example, see the Guide to implementing a coordinated vulnerability disclosure process for open source projects

On 2023-06-06 the OpenSSF best practices WG re-raised this as a problem. It was recorded as Best Practices WG issue 158, Revamp publishing of guides such as concise guides & scm guide.

OpenSSF staff quickly developed and deployed a solution. You can see the results here: Concise Guide for Developing More Secure Software. Notice that its URL is <https://best.openssf.org/Concise-Guide-for-Developing-More-Secure-Software>.

I think the new results look much better than the old view of the Concise Guide for Developing More Secure Software, whose URL was the much uglier <https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Concise-Guide-for-Developing-More-Secure-Software.md>

Let's call this new web page publication process the "simplest possible process" (SPP). The SPP focuses on trying to work with existing tools & minimize what needs to be done:

1. The easiest way to generate web pages suitable for publication, If you already have markdown on GitHub in a repo like we do, is to enable GitHub pages on that repo. This means that any change to the repo's main branch will immediately trigger recreating those pages and only the pages in that repo. The results rapidly deploy, since the trigger is known and a relatively small number of pages are involved. Making the results "pretty" requires adding a few files in a way that's trivial to do.
2. The easiest way to make the GitHub pages viewable is to assign a subdomain to every repo, e.g,. best.openssf.org for the best practices WG. This involves two easy one-time actions (add a DNS record and configure GitHub pages to use that DNS entry). GitHub will automatically get TLS certificates, so we quickly serve using https.

Once set up, these web pages are quickly and automatically updated once the repo's main branch is updated. The source materials are version-controlled, and the contributors can simply "work like they've always worked".

A side-effect of SPP is that every repo ends up with its own subdomain, e.g., best.openssf.org for the Best Practices WG. This would create a number of subdomains (a WG might have several repos that publish, not just one). I don't view that as a drawback, as this domain name is obviously part of OpenSSF. When certificates cost money those extra domains were a real problem, but with Let's Encrypt this isn't an issue. But perhaps others think that's a drawback.

There are an infinite number of other ways to do things, in fact, that's part of the problem :-). We can write workflows that push data to other places (but then we need to write that code and manage the keys). This uses default GitHub pages with the default process (Jekyll) and default template; there are so many other ways to generate pages. We can write workflows that gather the data (but then we need to write that code, and these typically have significant deployment delays because they're often periodic and would handle much more data). There are additional operational complications if we try to put everything in the domain openssf.org, as that is currently a WordPress instance. No doubt there are many many other ways to do this; if there are simple alternatives that'd be great to know.

I think the SPP is simple to implement and "does the job". However, others may disagree. I suggest the TAC and operations discuss this over time, because we want a system that's easy to manage.

There are two other issues I know of, but both have easy solutions:

1. Common CSS. If many repos use this approach, it would be a pain to have to individually update each one to update the CSS. The "obvious" solution is to have a repo for just the CSS, and have all other OpenSSF repos include that CSS. Then there would be one place to update CSS.
2. Abandoned domain names. If a repo is deleted, we also need to delete the repo entry. I think repo deletion is so rare that we could handle this as part of a manual process. We could also automate checking for dangling DNS entries if we wanted to.

If we decide on a different approach, the good news is that with the current page setups, we can reconfigure things to automatically redirect to their new locations. We couldn't automatically redirect people from the GitHub repo site, so even if this is a temporary process, it will still be a win.

[david-a-wheeler]

@SecurityCRob @brianbehlendorf @jennbly @hythloda - I had promised you that I'd write something about the process, which I'm now naming "Simplest Possible Process", and raise it up for discussion. I think this issue fulfills that promise. Let me know if I missed something important, I'll try to answer it.

[lehors]

I like the simplest possible process approach. I think there is a couple of pieces of metadata we are losing that should be added to the documents directly though: the WG the document comes from and, most importantly, the last modification date.

Unfortunately there is no built-in support to get the latter set automatically by GitHub Pages so this will need to be maintained manually which is a pain, but I for one find it very annoying to have a document without any publication date on it.

For what it's worth there is a jekyll-last-modified-at plugin one can use to set the date automatically but I looked into it and its use requires a custom workflow and config files that would clearly set us off the "Simplest Possible Process" path.

[david-a-wheeler]

Dates are important. I also noted this plug-in. We could try it. It appears to me that its date value can only modify metadata & layouts if we modified the layout.

Another approach to include dates is to simply have the date in the document itself (preferably in ISO format YYYY-MM-DD). Then it's visible, and it's sure easy. That might not be updated; one solution would be to check it & cause a failure.

If we want dates in the metadata we'll need to take added steps. The WHATWG Meta Extension proposals list various options; here is a summary. I think all that matters really is [dcterms.modified](http://dublincore.org/documents/dcmi-terms/#terms-modified).

It's possible to prefix the markdown with a yaml file to set values (easy to edit, but makes the markdown heading look odd). It's also possible to set values via the _config.yml file.

[lehors]

Dates are important. I also noted this plug-in. We could try it. It appears to me that its date value can only modify metadata & layouts if we modified the layout.

The plugin sets a variable you can use wherever you want in the page. I actually tried it: https://github.com/lehors/lehors.github.io

It does get the date, the format of which can be set to whatever your liking is. But the HTML page this jekyll builder generates is a lot more bare and would require a lot more config to get something closer to what the default GitHub Pages builder does, which is why I said it takes us away from the simplest possible process.

I do think the simplest is to stick the date in the document itself.

[david-a-wheeler]

I agree, "include the date in the document itself" also seems simplest to me. I would encourage using YYYY-MM-DD format.

So while dates are important, that doesn't seem to be a reason to avoid the "Simplest Possible Process". Does anyone see a serious problem with this approach? There are so many other ways to do this! Also, if someone needs something more exotic, we could handle that differently as an exception (e.g., they need to run a server-side application, not just distribute some documents or code). That said, I'd like to have something nicer-looking for our released documents other than .md files directly presented by GitHub's source code presentation.

[SecurityCRob]

Alternatively, we could just ask doc editors/authors to append a "last changed" date or the like at the head/foot of the document so it passed through to the fancy new website view.

Overall I like the simple process and I enjoy the results with the tests David and Amanda have run.

[steiza]

I'm in favor of this system!

[david-a-wheeler]

Thank you everyone! The TAC determined today that other WGs/projects/SIGs can this process if they'd like to.

Since dates aren't automatically inserted, they'd like groups to mark their published works with a date (the last modified date). The easy solution is to just include a date in the document/material.

[david-a-wheeler]

All: here is documentation for the "Simplest Possible Process": https://best.openssf.org/spp/Simplest-Possible-Process

[SecurityCRob]

Sent notice to WG Leads about SPP to encourage folks to start using it. Closing issue.