CONTRIBUTING.md instructions

[mkfreeman]

This PR updates the instructions in the CONTRIBUTING.md file to more explicitly outline steps involved. The intention is to get people with less development experience empowered to make changes more easily. @zanarmstrong @ananya-roy I'd love to hear your thoughts on this -- if you have time to walk through the updated instructions, that would be a very helpful assessment!

[ananya-roy]

• Under Development, it says to export the function to test/index.js. I think you meant test/plots/index.js

• Are there guidelines for documenting changes (like a README or in some cases a published Observable notebook with a live example?) as part of submitting a PR?

[mkfreeman]

Thanks @ananya-roy -- I've fixed the typo, and added a line about updating the README.md file (I'm not sure if there's any more detail we can provide as a general rule for updating the documentation).

[mbostock]

I want to reiterate some earlier feedback that was marked as resolved but was not addressed (at least, not explicitly).

The primary audience of CONTRIBUTING.md is the community (i.e. the public), not other Observable employees that can push directly to this repository. As such the recommended workflow for development, as @Fil pointed out, must be to fork this repository on GitHub rather than to clone this repository. In addition the {username}/{feature} branch naming convention need not apply; that is only needed because we, at Observable, by convention, share this repository.

[mkfreeman]

Thanks for clarifying // resurfacing -- I've updated the Set Up instructions for the general public. I also switched to the default https code that GitHub has users copy (in case some doesn't have SSH keys set up). Happy to switch that back if desired.

[mbostock]

We mention pull requests up above (I suggest we move this GitHub link above), so maybe this section could instead be more specific about our expectations for what makes a good pull request, or a good feature? Like, please include a motivating example, or why you think this feature will be useful. Or, please consider filing an issue, or checking for existing issues, before submitting a pull request, in case someone else has already thought about this topic. Or perhaps to start, this section could instead be called ## Documentation, and delete this sentence?

[mkfreeman]

I switched the last section to Documentation and moved the Observable instructions there.

[mbostock]

Isn’t this already covered below in the testing section, starting here?

To add a new snapshot test, create a new JavaScript file in the test/plots folder.

[mkfreeman]

Good point -- as someone less familiar with this structure of development, I wouldn't think to look in the test section for information about how to create a new example (so I've left a sentence directing them there).

[mbostock]

I still want to make a bunch of edits, but for the sake of expediency, I’ll just make them directly rather than going more rounds on this review. Thank you for the contribution. 🙏

[mkfreeman]

Thanks so much, @mbostock -- I'm hopeful that this will make it easier for more people to contribute to Plot (saving time in the long run)

[mbostock]

Apologies for the delay on this. I haven’t forgotten and will get to it soon.