Contribution guidelines


(Azriel Hoh) #1

Hiya, I’d like to collect what people’s thoughts are on how thorough we should be on contributions. From this we can come up with an issue template / pull request template. I know the following list is far more than we’d expect from casual contributions, but it’s what I think about. I’ve tried to keep the level of detail relatively high to cover a broad range of criteria.

Feature Contribution Completeness

  • Rationale: Is the rationale / use case tracked in an issue?
  • Design: Have multiple options been considered? If this is big, has there been an RFC?
  • Implementation: Does the code adhere to best practices? Is it easy to comprehend, performant?
  • Ergonomics: Are there sensible parameter defaults? Is the feature opt-in / opt-out?
  • Failure mode: If something goes wrong, are developers given an opportunity to handle it? Are there good error messages to tell what went wrong, and how to recover?
  • Testing: Is all new code automatically tested, for all cases? Has the feature been tested in its full intended use case?
  • Usage Documentation: Is there an end-to-end “How to” guide on how to use the feature? Is there a code example?
  • Discoverability: Is there a changelog entry? Mentioned in the weekly update / release post?

Bugfix Contribution Completeness

(probably incomplete, i just edicopied points from above)

  • Decision: Should the issue be fixed (are people relying on the bug)?
  • Failure mode: If the issue happens again, are developers given an opportunity to handle it? Are there good error messages to tell what went wrong, and how to recover?
  • Testing: Is the fix automatically tested? Has the fix been tested in the original discovered location?
  • Discoverability: Is there a changelog entry? If it is a breaking change, is this highlighted, and the semantic version updated?

(Joël Lupien) #2

I don’t think we should be too strict in our contribution process. It might drive first time open source contributors away if they get frustrated by the difficulty. Having to fix tons of reviews because you are learning rust and make mistakes it frustrating enough, no need to make them fill forms as well. :stuck_out_tongue:

Of course, if its more of a suggestion template than a guideline, that could be very beneficial.


(Azriel Hoh) #3

Definitely! It’s likely that when there’s a PR template, people tend to think “these are the rules, I must abide”. Could go with the “must-haves” at the top of in the template, and an optional section for “copy paste any extra relevant parts”.