Add a ToC to the top of the CONTRIBUTING.md file#7815
Conversation
Alhadis
left a comment
Alhadis
left a comment
There was a problem hiding this comment.
The vast majority of people coming to this file are first-time or very infrequent contributors, and the first thing they should see is whether or not their language or file-extension of interest is even eligible for submission in the first place. If and only if the usage criteria is met does it make sense to go into depth about setting up one's workspace.
Here's how I'd structure this document:
Toggle table-of-contents
-
Rules for submissions
-
Adding entries
- Notability requirements
- Adding languages
- Associating new file extensions with existing languages
-
Modifying entries
- Fixing misclassified files
- Syntax highlighting
(Preamble about TextMate grammars)- Fixing highlighting mistakes (or rather, who and where to report them to)
- Adding or replacing grammars
- Changing language colours
-
-
Preparing a pull-request
-
Setting up your development environment
- Developing locally
(Steps for cloning and bootstrapping the Linguist repo)- Dependencies
(We shouldn't waffle on too much about individual libraries;
users need not know whatcharlock_holmesis or does, only that
it's a Ruby Gem required by Linguist. The majority of this section
should be comprised of platform-specific one-liners to install
the necessary packages, with off-site links to the package manager's
docs included to answer any questions that novice users might have
about installing stuff on the system they're running)
- Dependencies
(The next two sections are about alternative workflows that are, in a manner
of speaking, shortcuts. Ergo, they should follow on from the “normal” procedure
of hacking on this repository that are more immediately familiar to Git users, even
Git users who've never contributed to Linguist before).- Using GitHub Codespaces
- Using the dev container locally
- Developing locally
-
Testing your changes
(This might be a good place to add subsections regarding common failures,
particularly those produced bytest_pedantic.rb).
-
(Note that this requires some wordsmithing and literary surgery; obviously, these are tasks I'm tacitly volunteering to tackle).
Thing is, it's a reasonable assumption that many users with prior contributions elsewhere are used to skim-reading docs like this one in search for a familiar-looking setup command like Conversely, if the first thing they're greeted with is an unusual or elaborate setup procedure, they might interpret it as "mandatory for contributing" and not "purely optional for seasoned Git hackers". That alone might be a turn-off for users with less time to spare than others for contributing to open-source projects. (I've submitted PRs on my lunch break, for example, but only because the process was easy and immediately familiar). Opening this half of the document with the Codespaces and devcontainer sections might make those workflows more visible to users, but since the Developing locally section can be drastically cut down in length by omitting explanations that are unnecessary for development, it means leading with that section won't bury the visibility of the alternative, more efficient workflows. |
|
Also—and I realise this is purely anecdotal—but the mistrust I feel towards "efficiency" solutions offered by companies that are also hawking AI products leaves me reluctant to want to try or even trust any shortcuts being advertised (even if no AI is involved whatsoever). This is probably just a "me" issue, but it's worth considering how many other stubborn Unix hackers have the same mentality towards LLM-powered tools. |
Oh, I'm 100% with you here. In this case, I'm only suggesting it because I'm incredibly lazy and I don't want to have to deal with local dev env setup issues when they can be prevented very easily 😁. |
2 participants
Description
This PR adds a table of contents to the top of the
CONTRIBUTING.mdfile to help viewers quickly find the section applicable to them.Hopefully this will help reduce the number of PRs where users haven't followed instructions because they're hard to find.
Checklist:
N/A as this is just a doc change.