Repository navigation
Repository cleanup to eliminate dead links #190
Description
Activity
The @PowerShell/powershell-committee has discussed this topic previously but the main concern was making state of RFCs easy to find hence the individual folders. Ideally, if we can generate a html table that had filter/sort capabilities perhaps nightly (via AzFunctions), that would resolve this.
If we roll with the GH pages suggestion, The Jekyll build agent can use the Markdown headers to determine where to put each RFC doc. A few Liquid tags to filter things on the rendered page, and you're done, nothing too fancy.
Even without the HTML, Markdown with links that refer to different locations in the appropriate document to allow viewers to go through the various stages, plus search.
Anything would be better than the mess of dead links that is there today, and when I follow a dead link (a link to an RFC that has been moved), I end up having to use search or some other technique to find them. I don't think that RFCs are easy to find right now at all, which makes me wonder why the @PowerShell/powershell-committee was concerned in the first place.
@PowerShell/powershell-committee reviewed this, we agree that the current repo is a bit of a mess. Having a single
rfcfolder makes sense as long as tables can be dynamically generated to show the different stages making them easy to find. We discussed using GitHub Pages with GitHub Actions to generate this on PR open and PR merge or an AzFunction (perhaps incorporating into PoshChan-Bot). We currently don't see this as a priority, but if someone in the community is willing to take this on, ping me and I can enable certain capabilities in this repo to enable this.Steve Lee (@SteveL-MSFT) i have already open an issue #191 with others languages examples . When this one will be closed, i will be happy to work on it.
@PowerShell/powershell-committee while we do see this is a small inconvenience, we don't believe this critical for the ongoing effort to address it.
I'd like to propose some cleanup to eliminate the dead links that are created during the processing of RFCs.
Currently as RFCs move from a PR into the various "stage" folders (Draft, Draft-Accepted, Experimental, etc.), each move creates dead links, because the RFC files themselves get moved from one folder to the next. I've followed dead links to a number of RFCs from issues in the PowerShell repository, tweets, etc., only to have to dig around to find the RFC in a different stage. This isn't a good model to follow long term.
Instead, how about we fix the dead links going forward by doing the following:
RFCfolder, and keep them there forever. Or, if the number of files in one folder is a concern, eventually move them into anArchivesubfolder when they become very, very old. Given the low volume of RFCs, however, having a single folder will probably do for quite a while.At any rate, you get the gist of this issue: we should eliminate the possibility of dead links so that contributors can link/refer to RFCs regardless of their current status, and the links will work. Since the RFC documents contain YAML with the current stage at the top of each document, anyone following a link will see front and center what stage the current RFC is in, as long as that metadata is properly maintained.
Joey Aiello (@joeyaiello) Thoughts? Is this PR-able, or do you have internal tooling that would break if this was changed in a PR?