Closed ltagliaferri closed 1 year ago
FYI, I keep seeing this, for example here: https://docs.sigstore.dev/policy-controller/overview
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
@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.
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 ?
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 :)
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
Thank you :)
Just realized that adding wordage won't do any good if the returned version is the old version, so yeah, never mind :)
@ltagliaferri let me know if need any help to setup the infra
Reopened since we're still seeing this, #114 has some screenshots to show it
Would there be any objections to replatforming this site to Hugo?
+1, would be great to understand how much work that would be
@ltagliaferri any thoughts here? Folks keep getting bit by this :(
@ltagliaferri told me that @smythp might be able to look at this :)
I added @smythp as collaborator pending invite, will reassign to him once that's all set
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.
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
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.
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.
Here are some initial issues that will need to be worked through:
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.)
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.
Here's a rough plan for a replatform.
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.
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!
Excellent! Looking forward to the content reorg, and to putting the new Hugo site into production. Thanks, @olivekl and @jonvnadelberg .
Huge thanks for getting this done! Not only did the bug get fixed, but I find the new site more visually appealing!! 👍
Thanks, appreciate it! I also think Hugo will have some advantages over the previous stack, even beyond the obvious (faster builds, fewer rendering issues).
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.)
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.
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.