Repository cleanup to eliminate dead links

[KirkMunro]

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:

1. Place all RFC documents into a single RFC folder, and keep them there forever. Or, if the number of files in one folder is a concern, eventually move them into an Archive subfolder when they become very, very old. Given the low volume of RFCs, however, having a single folder will probably do for quite a while.
2. Update README.md with multiple 2-column tables containing a list of all RFC files in each of the respective stages. Column 1 would contain the RFC filename (link). Column 2 would contain a brief (1-2 sentence) description. This could alternatively be maintained in a file other than the README, but having this in the README makes this information visible to anyone visiting the community.
3. Update the PR template requesting users create a new file from the RFC template in the root of the repo and add an entry to the Draft table in the README.md file (or other file if it is stored elsewhere).
4. Optionally add commands to the RFC module that was recently created to do automatically create the file and table entry from a single command invocation.

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.

@joeyaiello Thoughts? Is this PR-able, or do you have internal tooling that would break if this was changed in a PR?

[SteveL-MSFT]

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.

[vexx32]

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.

[KirkMunro]

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.

[SteveL-MSFT]

@PowerShell/powershell-committee reviewed this, we agree that the current repo is a bit of a mess. Having a single rfc folder 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.

[fMichaleczek]

@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.

[JamesWTruher]

@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.