Caching issue

[ltagliaferri]

There is an issue where users are reporting landing on older versions of the docs site and need to hard reset multiple times. I have cleared and re-deployed the Netlify cache but this did not address the issue.

[vaikas]

FYI, I keep seeing this, for example here: https://docs.sigstore.dev/policy-controller/overview

[vaikas]

FYI, I just got bit by this again. I'm not sure how to reopen this but I don't think it's fixed. @ltagliaferri @cpanato

[vaikas]

@cpanato @ltagliaferri I keep getting this, just right now again (see the deprecated policy-controller behaviour on the right side of the page). I'd like to reopen this. I was thinking of putting something in the page about 'if you see this, hit refresh' but it seems wrong to me.

[ltagliaferri]

Tracy and I are talking about a replatform off of nuxt.js, I can start a new issue about that and add this feedback in, wdyt @vaikas ?

[vaikas]

I think that sounds great :) Do you have any rough idea about the timelines. As in, for the time being, should we add the wordage about the possible need to refresh to make sure folks get the fresh version? It's also goofy that the version that seems to be cached is always the same, not like the version-1, but like one particular version that just won't go away lol :)

[ltagliaferri]

Yeah, I have no idea why there is an issue, I think we can add some language about refreshing, yes. I will talk to Tracy about possible timeline for replatform and let you know

[vaikas]

Thank you :)

[vaikas]

Just realized that adding wordage won't do any good if the returned version is the old version, so yeah, never mind :)

[cpanato]

@ltagliaferri let me know if need any help to setup the infra

[haydentherapper]

Reopened since we're still seeing this, #114 has some screenshots to show it

[ltagliaferri]

Would there be any objections to replatforming this site to Hugo?

[haydentherapper]

+1, would be great to understand how much work that would be

[vaikas]

@ltagliaferri any thoughts here? Folks keep getting bit by this :(

[vaikas]

@ltagliaferri told me that @smythp might be able to look at this :)

[ltagliaferri]

I added @smythp as collaborator pending invite, will reassign to him once that's all set

[haydentherapper]

Can we add collaborators via https://github.com/sigstore/community/blob/main/github-sync/github-data/sigstore/repositories.yaml? Otherwise Pulumi gets out of sync.

[ltagliaferri]

There are a few folks in the docs repo manually, I'll open a PR there to add them all then. Thanks for calling that out @haydentherapper

[smythp]

Replatforming to Hugo

I've done a look into replatforming to Hugo, including some preliminary work on configuring the site and transferring the contents. Replatforms tend to be a pain, but I do think this one will be on the less painful side.

Preliminary Work

I've set up a site with the theme and moved some content as a test. So far, I'm not seeing major problems or show-stopping issues with these transfers.

I selected a theme called "Docs" maintained by Netlify. You'll find the design is not dissimilar to the current documentation site. The demo is below, I encourage you to click through to the second link as well to see how documentation is laid out. The biggest issue working with the theme so far is that the name "docs" is quite generic and difficult to do searches on. Overall, I've found it well-maintained, and they take stuff like the lighthouse score pretty seriously.

• https://getdoks.org/
• https://getdoks.org/docs/overview/introduction/

Replatforming Work and Potential Issues

Here are some initial issues that will need to be worked through:

• Moving YAML while preserving data. While a few fields are the same, many are not. I've found a simple way to preserve the content ordering without a lot of manual work, so that should not be an issue.
• Changing the home page to be an introduction, i.e. a content page. Currently, the theme is set up for the index page to be a full website, assuming that there will be a blog, team page, and so on (you can see this in the first link above). I assume that's not what we want here, and that will take a bit of work to change in a non-brittle way.
• The replatform is likely to break current CI. I haven't looked closely at what CI is in place on the docs repo, and could use any input from those that are more familiar.
• There's a decent amount of smaller issues and details that will require attention.

In theory, and this is a bit surprising to me, the site should be able to be set up to break a minimum of internal links to content and static resources. However, I've done enough of this sort of thing to figure that there will be some issues there, or at least I'd be surprised if there weren't. We may want to run a broken link checker on the site after the initial replatform.

There will be some design differences between the old and new site by default. For example, the code examples aren't solarized. We can decide which of these are fine and which we might want to manually change when I have a demo site up. (Personally, I've liked most of the design differences so far.)

Making the Switch

Something that will require coordination here is that ongoing work on the docs site may make a full transfer of content difficult. That is, as I move content to a test/demo site, moved content is likely to become stale as we add to and edit the current site. For that reason, in creating the demo/test site, I'll do a minimum pass on moving the content, but I won't emphasize that element. When the site is in decent shape, we might consider either pausing merging PRs for a week or just ripping off the bandaid and switching over, then checking the site over for reversions. The former would probably expose users to less weirdness, but the latter would slow down contribution less.

Draft Plan

Here's a rough plan for a replatform.

1. Shortly, as early as next week, I'll share a test/demo site. I'll do a first pass to move all content, but as above, it may become stale.
2. In the meantime, we should choose whether we're going to plan for a pause in contributions. It will be helpful to have a date in mind. We should assume there will be more problems and issues right after the replatform in the immediate short term.
3. When ready, we swap the current site for the new site. We should make sure to preserve the existing commit log, i.e. the replatform should be done in one commit on top of the current history. I have a way in mind to go about this, but would value input.
4. Again, we should prepare for unanticipated issues, both in the process of switching and in the period right after.

Things That Would Be Helpful

• Many of you have more experience with the site and its quirks. In the preliminary work I think I've got a handle on most of the major issues, but if there are oddnesses of the current site that you think it's likely I've overlooked, please share. Probably best to err on the side of not assuming that I've noticed everything, I won't be offended. :)
  • Any input on how to handle automation's and CI connected to the site would be valued.
  • Thoughts on how to handle the logistics of transfer to the new site (pausing contributions, timing, etc.) would be welcome.

After the Transfer

From where I'm sitting, I can't guarantee that the replatform will fix issues with caching. However, working with the current site and the Hugo site, I do think Hugo will be faster and more stable. There are fewer deps and I don't have to run code to work around that SSL issue. This project is primarily Go-based, so I think Hugo is a good choice.

The layout of the new site will be mostly familiar to prior contributors, especially the content folder, which is touched most often.

The next step will be to share a demo/test site. I'll update this issue when that's live. For now, I'll just run it from my own account, but happy to create a replatform repo on here if that would be preferred.

[olivekl]

Replatforming to Hugo

To support these plans, @jonvnadelberg will submit a PR soon to restructure the docs (without editing or changing the content) so that the structural changes can be merged before the migration. Then we'll pause documentation PRs while the migration takes place. Post-migration, we can address broken links or anything that got lost in the shuffle and then resume editing the content. Thank you for all this, @smythp!

[smythp]

Excellent! Looking forward to the content reorg, and to putting the new Hugo site into production. Thanks, @olivekl and @jonvnadelberg .

[ltagliaferri]

Closed by https://github.com/sigstore/docs/pull/222

[vaikas]

Huge thanks for getting this done! Not only did the bug get fixed, but I find the new site more visually appealing!! 👍

[smythp]

Thanks, appreciate it! I also think Hugo will have some advantages over the previous stack, even beyond the obvious (faster builds, fewer rendering issues).

[olivekl]

This looks great, thank you for all the work!

There's an issue with some links that are broken on the landing (index.md) page. Under "How to Use Sigstore", the links for "I want to... (Quickstart, Sign a Blob, etc)" are broken. I believe they're missing a docs path:

https://docs.sigstore.dev/signing/quickstart/ --> https://docs.sigstore.dev/docs/signing/quickstart/

We can open a PR to fix this, but is it likely any other links might have been affected? (This may not be related to the re-platforming at all! It could have been introduced by the recent re-structuring.)

[smythp]

That will have been due to the replatform. Let me run some automated checks and I'll try to get as many broken links as possible in one sweep.

Thanks, and keep an eye out for more regressions. The replatform was pretty sweeping, I'm sure we'll find more.