carbon-lang
carbon-lang copied to clipboard
carbon-language
Include proposal titles in proposal file names
Scanning the proposals directory is currently not very user-friendly, only the proposal number is visible for each proposal:
To give a better idea what each proposal is about, without having to open each of them, the proposal title could be added at the end of the file names, for example:
- p0024-generic-goals.md
- p0029-linear-rebase-and-pull-request-github-workflow.md
- etc.
This would make it easier to find the right proposal, for example when looking for a proposal related to a subject. Swift proposals and Rust RFCs also use this naming convention.
This convention could also be automated in the new_proposal.py script.
(This would break links outside the repo pointing to trunk such as https://github.com/carbon-language/carbon-lang/blob/trunk/proposals/p0024.md, but finding the correct proposal would still be quite easy since they're sorted alphabetically. And if we do this, it's better to do this now rather than when the project has grown even bigger.)
I'm not going to weigh in too heavily on this, but I will note that while there's an advantage of explicitness, but a couple cons of (a) making the directory listing really long because filenames are really long, and (b) making links fragile if the proposal title changes. If there's a website (per #1492), that may offer a different approach to ease-of-skimming by rendering a proposal list with titles.
If this is accepted, I suggest that (1) we should probably have a pre-commit to enforce naming to prevent filenames from skewing from doc titles, and (2) we should probably add a couple more digits to the front at the same time.
Regarding point (2), we're rapidly closing in on #10000 which would pass the current 4-digit titles. While I suspect 6 or 7 digits is enough for many years, another option would be to just not zero-pad anymore, although that in turn loses proposal ordering advantages. Either way, we should avoid renaming all proposals multiple times because every link would need to be updated.
Yeah, listing proposals on the website would also be useful. It would also open the possibility for other improvements, such as highlighting current on-going proposals, like Swift does: https://apple.github.io/swift-evolution/.
But it would still be nice to have an improved experienced on GitHub and the local filesystem also. I noticed that at least Swift proposals and Rust RFCs also append the title to the file name.
Regarding point (1), that would be useful even for our other docs where we have mismatching titles (example). Though admittedly not a huge issue.
Regarding point (1), that would be useful even for our other docs where we have mismatching titles (example). Though admittedly not a huge issue.
The issue in general is that we typically are okay with some divergence. e.g., README.md files need to be named that way even if they are better not to be titled "README" internally. We also have things like https://github.com/carbon-language/carbon-lang/blob/trunk/docs/design/generics/appendix-coherence.md where the title and name deliberately diverge. The problem with pre-commit is that it's strong enforcement, and so becomes difficult to universally apply.
Leads are ok with adding the title, and a pre-commit check to keep things consistent.
Leads are ok with going to 6-digits at the same time.
Want to write a PR to implement this?
