[Documentation Suggestion] How To Contribute To Unit Tests

[srcmake]

Description
I'm new to the Node project and I want to help contribute, and I've seen suggestions that a great way to contribute is to look at the code coverage report, find something that doesn't have full coverage, and write/add to tests to help the coverage be more complete.

However, the actual steps to do that are a bit vague (the code coverage website is a bit hard to understand), and this process isn't documented in this project. (I actually heard about doing this in this medium article.)

Solution
Can we add a section in one of the contributing documents (I guess either on the website or maybe a new doc (that gets referenced in CONTRIBUTING.md) to list out the steps of how to either use the code coverage tool to find code that's untested, and how to help add tests (or add to current tests) to contribute?

I'm not sure if we should treat this in two parts (one part being documentation on how to use the code coverage tool, and another on how to use contribute by using it to find untested code), or to make just one document.

[Trott]

The how-to-write-a-test-for-Node.js-core part is covered in https://github.com/nodejs/node/blob/master/doc/guides/writing-tests.md. (Not saying it's perfect and can't stand some improvements though.)

[srcmake]

Hmmm you're right. Good call.

But it still seems like the project doesn't explicitly state that writing tests are a good way to contribute (because the CONTRIBUTING.md document mostly links to the Issues and Pull Request documents).

I wonder if CONTRIBUTING.md document should also link to the Writing Tests document as a way to communicate that finding uncovered lines of code and writing tests for them are an easy way to contribute. (And I only bring that up because of that medium article.) I'm not sure if it would be weird to also add the headers/links to the sections of writing-tests.md in that CONTRIBUTING.md doc though the same way Issues and Pull Requests are shown.

[Trott]

But it still seems like the project doesn't explicitly state that writing tests are a good way to contribute (because the CONTRIBUTING.md document mostly links to the Issues and Pull Request documents).

I'm going to push back a little bit on the idea that CONTRIBUTING.md should be a guide for newcomers who just have an idea that they'd like to contribute but don't know what they want to contribute. There are places for those folks (like nodetodo.org), but CONTRIBUTING.md is what gets linked to when someone is opening a pull request. So, by that point, typically, someone already knows what they're trying to do. They need a concise, scannable checklist of things to check: commit message format, remembered to add a test and/or update documentation as appropriate, etc. The more other stuff that gets crammed into CONTRIBUTING.md, the less useful it becomes.

I wonder if CONTRIBUTING.md document should also link to the Writing Tests document as a way to communicate that finding uncovered lines of code and writing tests for them are an easy way to contribute.

It is linked in doc//guides/contributing/pull-requests.md, which CONTRIBUTING.md links to.

[Trott]

Thinking more about it, and looking at the existing CONTRIBUTING.md, a link to nodetodo.org or similar guide may make sense if it can be done in a non-obtrusive way that doesn't feel shoe-horned.

On the other hand, it could also easily go the other way: Remove stuff from CONTRIBUTING.md, make it a guide for people who are about to open a pull request, and maybe include a single link to some kind of "So, you'd like to contribute to Node.js but don't know where to start?" guide.

[srcmake]

I agree that just adding "you can contribute to Node.js by writing unit tests" might not fit well in CONTRIBUTING.md, but there are some other topics that would be nice to have linked all in one document for newcomers. (Ex. Collaborators, Pull Requests, Issues, Codebase Structure. Working Groups, TSC, nodetodo.org, etc.)

I'm not sure if CONTRIBUTING.md should be revamped or not. The structure does seem a bit unusual in it's current implementation (in that it basically only links to very few other documents (Issues and Pull Requests)). (And I do think the Pull Request document is complete and done really well in it's current implementation.)

The only reason I bring this Issue up is because, as someone who recently looked into this project, I think there's a lot of information all over the place, and I don't think they're linked together that well. (I had like 12 tabs worth of documents to read while going through the guides.)

(Since this Issue might seem a bit inaccurate (since it only brings up testing), maybe it's best to close it now?)

[Trott]

The only reason I bring this Issue up is because, as someone who recently looked into this project, I think there's a lot of information all over the place, and I don't think they're linked together that well. (I had like 12 tabs worth of documents to read while going through the guides.)

I certainly agree that the organization and discoverability of the existing documents could stand a lot of improvement.

The current CONTRIBUTING.md structure arose because our CONTRIBUTING.md got far too long and unwieldy. The current organization was originally modeled on ESLint's CONTRIBUTING.md: https://github.com/eslint/eslint/blob/d662b178c7dad193201564d16f7977af2f81ebcf/CONTRIBUTING.md

[Trott]

/ping @nodejs/documentation