[Issue 416] Update Contributing Guidelines

[acouch]

Summary

Fixes #416

Time to review: 30 mins

Changes proposed

Adds external and internal contributing guidelines.

Context for reviewers

It seemed simplest to break these apart since the audiences are different.

There is a lot to review, so might be best to discuss first.

[andycochran]

Should the CONTRIBUTING_INTERNAL.md file just be called CONTRIBUTING.md? I think that filename is important to have, no?

[acouch]

@andycochran great suggestion. I updated filename.

[decause-gov]

I really like what I'm reading in the text about development guidelines (squashmerge, CalVer, etc...) this all looks great! :) I am curious though why we want to have separate guidelines for internal and external contributors?

• What is the difference between an internal/external contributor?
• Is this because we are depending on some kind of privileged/paid for/internal-only infrastructure somewhere?
• Is there a separate internal repo, other than the public repo, where development is also happening?

There are valid reasons for internal/external repo patterns (e.g. specific security considerations, internal systems testing, among others), however, Internal Forks are more often than not a costly pattern to maintain, and divide your development resources and create duplicate work. Sometimes this duplicate work is necessary, but, if it can be avoided, it will be worth it in the longrun.

Understanding whether a project is "internal first" or "external first"--whether the public repo is the 'source of truth' where reconciliation is done and then merged internally (e.g. "we're just another downstream user and develop in the open"), or whether the public repo is the place where after-the-fact releases are cut after internal merging is completed (e.g. we primarily cut periodic releases and develop mostly in private) is an important decision.

Perhaps I'm just reading too far into this, and we want specific instructions for folks who are internal HHS employees/contractors v.s. the general public, which is also valid, but, even maintaining two sets of CONTRIBUTING.md files can lead to duplicate work, and sometimes confusion or ambiguity. If we can keep one version of CONTRIBUTING.md, it helps to reduce that maintenance and cognitive burden, though there may be valid reasons for doing so.

Happy to discuss further, thank you for putting thought and intentionality into how contribution works 🙏

[acouch]

@decause-gov Thanks for asking and digging into this.

I am curious though why we want to have separate guidelines for internal and external contributors?

I thought a lot about this myself. There are a couple of key differences in the internal and external contributors that drove me to separate the pages. Some of them are:

External contributors often need more context and support, and from a maintainers perspective, I think we want to give them MORE support, or at least more focused support. In the external doc I included the following which is directed to external contributors and not helpful for internal:

🎉 First off, thanks for taking the time to contribute! 🎉

We're so thankful you're considering contributing to an open source project of the U.S. government! If you're unsure about anything, just ask...

External contributors also have multiple ways of contributing, however CONTRIBUTING.md is more focused on developers and the SDLC. The "How Can I Contribute?" addresses items that internal team members don't.

The "Code Contributions" section is the one focused on devs. I am trying to treat the CONTRIBUTORS.md as place the source of truth there, and just calling out what is different for external devs, specifically forking.

Understanding whether a project is "internal first" or "external first"... is an important decision.

I think this is the most important thing. I'm wondering, given some of the differences I noted, what is the best way to have good documentation for internal and external folks, while communicating that we actually want and will support open contributions?

Maybe explicitly saying that? Swapping the names so the CONTRIBUTING.md is focused on external?

I've gone back and forth, but combining them into a single document does feel like it is making more of a mess than providing clarity, though I am open to it.

Would be great to get more feedback @lucasmbrown-usds @widal001 , thoughts?

[andycochran]

Swapping the names so the CONTRIBUTING.md is focused on external?

I like this thought. It makes the primary entry point more general and applicable to a wider audience. Then, if devs wanna dig in and contribute more (code), they can follow a link that wades into the deep end.

The primary benefit of separate files is brevity. And I suppose it makes editing them easier. But I don't think these files (or file) will be all that active.

We might consider appending the "internal" info to the end of the general contributing doc, and adding a brief mention in the first section — e.g. "Project team members with write access to this repository, go to [Internal Contributors Contributing Code]."

We might also consider a word other than "internal." We really just mean "those who CRUD" and "internal" could go stale, depending on how the community and partnerships grow.

[SammySteiner]

Looks good.
I left some suggestions/nits

[acouch]

I looked at a number of external examples of open source projects that use both CONTRIBUTING.md with an external contributor focus, and DEVELOPMENT.md for the nuts and bolts of development. I updated the language in what is now DEVELOPMENT.md to be more inclusive for external contributions.