Add contributor guidelines & code of conduct update - #679
Conversation
- new contributing guide - update start contributing guide to reference new guide - add use your own words to code of conduct
Links to start contributing and learn pages.
|
|
||
| ## Start With an Issue | ||
|
|
||
| To contribute to a Typelevel project, start a conversation before creating a pull request. This can be in a new issue, continuing the conversation in an existing issue, or any other communication channel being used by the project. This gives maintainers and other contributors a chance to work with you on your idea at an earlier stage to make sure it is an acceptable contribution. |
There was a problem hiding this comment.
does plugging the typelevel discord make sense here? or link to a resource listing communication channels
There was a problem hiding this comment.
I don't really want to have another discord link that might have to be hunted down to update if the link needs to be changed. Also, the right communication channel is usually the project's issues page, which is separate for every project. In the diataxis taxonomy, this in intended to be a reference for the appropriate way to contribute, not a how-to guide (which the start contributing page more functions as).
There was a problem hiding this comment.
Hmm. Not sure I 100% agree -- I mean, this paragraph is providing how-to information. And given that most projects have individual channels in the Discord (and some specifically have dev channels), I suspect that it would sometimes be appropriate to start with an "is this even a good idea?" conversation in the Discord.
So a "linked at the bottom of this page" reference might be appropriate here.
There was a problem hiding this comment.
discord link that might have to be hunted down to update if the link needs to be changed
This is something we should fix/address with Laika. We can set the Discord invite url once as a global config variable and reference it in all the places.
| - **Technical overview:** Briefly explain each of the changes in this pull request, and why they are necessary. | ||
| - **Testing:** How you tested the pull request, and the results of your testing. | ||
| - **Discussion:** How you see the pull request in context. For example, list risks and caveats and how they could be mitigated. If existing projects may be negatively affected, you should disclose this here, with particular attention to possible compatibility breakages and regressions. | ||
| - **Additional work:** If applicable, highlight anything you need help with or feedback on, and describe any necessary or potential follow-up work. |
There was a problem hiding this comment.
I'd encourage the specific usage of Github comments to help localize and contextualize the thing that needs extra review power/feedback/teaching
There was a problem hiding this comment.
I'd rather not go too deep into the mechanics of how Github PRs work. This document is talking about what you should do, not how exactly to do it.
jducoeur
left a comment
jducoeur
left a comment
There was a problem hiding this comment.
A few thoughts below, but looks good!
| - **Gracefully accepting constructive criticism.** When we disagree, we are courteous in raising our issues. | ||
| - **Using welcoming and inclusive language.** We're accepting of all who wish to take part in our activities, fostering an environment where anyone can participate and everyone can make a difference. | ||
|
|
||
| - **Using your own words.** We take the time to communicate with our own thoughts and writing. |
There was a problem hiding this comment.
Sounds right to me -- please make sure to get a thumbs-up from the CoC committee. (Attn @valencik and @samspills)
|
|
||
| ## Start With an Issue | ||
|
|
||
| To contribute to a Typelevel project, start a conversation before creating a pull request. This can be in a new issue, continuing the conversation in an existing issue, or any other communication channel being used by the project. This gives maintainers and other contributors a chance to work with you on your idea at an earlier stage to make sure it is an acceptable contribution. |
There was a problem hiding this comment.
Hmm. Not sure I 100% agree -- I mean, this paragraph is providing how-to information. And given that most projects have individual channels in the Discord (and some specifically have dev channels), I suspect that it would sometimes be appropriate to start with an "is this even a good idea?" conversation in the Discord.
So a "linked at the bottom of this page" reference might be appropriate here.
|
|
||
| If you authored every part of your contribution and own the rights, this is not a problem. You can submit your contribution without reading further. | ||
|
|
||
| However, any code or assets you took from somewhere else, including code generated by AI, may be subject to copyright or patent rights, which you must respect. In such cases, you need to check the license of the material. |
There was a problem hiding this comment.
including code generated by AI
I would bet that we're going to get arguments about this, given that current Copyright Office policy says otherwise, and that there's basically no practical way to know about copyright or patent rights over AI contributions.
This is a deeply messy topic, nowhere near settled in terms of legislation or litigation, and I have mixed feelings about whether it's worth saying this outright, or just leave the point implicit.
There was a problem hiding this comment.
I left this part verbatim from the Godot guidelines. I have no strong feelings about keeping or removing it. Though I'd be surprised if AI generated code get a free pass on patents (are software patents still a thing in the US? I forget.)
There was a problem hiding this comment.
are software patents still a thing in the US? I forget.
They are, sadly. I'm not aware of any settled case law around the intersection of software patents and AI yet, but IANAL, so I dunno how that factors in.
There was a problem hiding this comment.
Decided to have Kagi Research (my general-research tool of choice) do some quick summarization, which resulted in a fairly interesting thread: https://assistant.kagi.com/share/d21a11b0-19a9-4abd-9f11-e59ac3b18da9
tl;dr -- software patents are still a thing, yes, and "generated by AI" is probably irrelevant when it come to violation: patented is patented. AIs probably can't create patents, but when they violate them, it's probably exactly the same as when a human does so.
(Note: I hate software patents with a burning passion and wish that whole notion in law could be just plain expunged. I'm still vaguely embarrassed that my father's boss apparently invented the idea, many decades ago, and moreso that I have my name on several. But yes, it's something we have to live with.)
How does that affect contributions? IMO it's a minefield. Violations tend to be accidental (unlike copyright), and the average developer has no way to know if they're violated patents. It's a whole field of law that is heavily governed by security-through-obscurity: you're only in trouble if somebody notices that you've violated a patent, and AIUI you're generally better off not trying very hard to figure out if you did so. (Since if you do the research and find that you have arguably trod on an existing patent, now you have evidence subject to discovery of intentional violation.)
So while I care a lot that contributors not intentionally violate patent, it isn't even remotely obvious how far we should go beyond that, beyond the statement of "don't do that". The whole framework of software patents is pretty hostile to open source. (And indeed, to software development generally.)
And all of this is still somewhat hypothetical: there isn't a lot of settled case law around it yet.
If any members of the @typelevel/board have thoughts here, they might be useful.
Co-authored-by: Justin du Coeur, AKA Mark Waks <jducoeur@gmail.com>
armanbilge
left a comment
armanbilge
left a comment
There was a problem hiding this comment.
First pass with mostly smaller comments and nitpicks. I want to take a second pass later to think more about some of the phrasings. Overall excellent and thank you so much for your work on it.
| @@ -0,0 +1,38 @@ | |||
| {% | |||
| author: ${foundation} | |||
There was a problem hiding this comment.
We could add a TSC author and make it a co-authored post. I would like to somehow give credit to the TSC for your work. (Alternative to co-authoring, could give credit in the post.)
| author: ${foundation} | |
| author: [${tsc}, ${foundation}] |
|
|
||
| You must be mindful of the copyright and patent rights of anything you submit. | ||
|
|
||
| If you authored every part of your contribution and own the rights, this is not a problem. You can submit your contribution without reading further. |
There was a problem hiding this comment.
Since we are stating all of this, we should probably mention the case where a contributor's employer owns the rights and that they should do whatever Corporate Due Diligence™️ is needed to ensure they can legally contribute it.
|
|
||
| > - **Using your own words.** We take the time to communicate with our own thoughts and writing. | ||
|
|
||
| This is Typelevel's current restriction on AI-generated content: Community members should not be using these tools to generate content for others to read. |
There was a problem hiding this comment.
English is not my first language, but by my reading this sentence forbids LLM-generated source code contributions. Since the next section explicitly allows these, I think this is not intentional. (Note: source code in a PR is "content for others to read". Namely, for the reviewers. At least, I don't know of a way to review a PR without reading the diff...)
| With agentic coding tools coming into wide use, it has become very easy for potential contributors to write code without thinking, resulting in contributions that are not actually helpful. To mitigate this, the contributing guide has two guidelines regarding AI-assisted contributions specifically. Individual projects may have additional restrictions in their own contribution policies, but the below is our default expectation: | ||
|
|
||
| * We **are** allowing AI-assisted coding contributions. We expect contributors to disclose when they have used such tools and be responsible for their contributions regardless of how they are coded. | ||
| * We are **not** allowing AI generated pull requests, issues descriptions, or other prose. We expect that contributors understand their work well enough to explain it themselves. |
There was a problem hiding this comment.
If LLM-generated PR descriptions are disallowed, while LLM-generated source code changes in a PR are allowed, maybe this sentence could make this clearer.
|
|
||
| Pull request descriptions, pull request comments, discussions, Markdown documents, Discord messages, and such are all examples of something very important: human beings communicating with other human beings. Generating a long and wordy description of something which can be more concisely and organically expressed serves no one's best interests. Rubber stamping something done even more autonomously by an AI in your name is even less useful. | ||
|
|
||
| Maintainers have very, very limited time that they are able to devote to their projects. As a contributor, please respect the time they are giving you by giving them your attention when you interact with Typelevel projects, rather than allowing an agentic system to step in the way. |
There was a problem hiding this comment.
I like the 2nd sentence, but not the 1st one. Is the "very limited time" really the thing to point out here? It is certainly true. But I think the "respect the time of your fellow human beings" (paraphrased) from the 2nd sentence is more important.
|
|
||
| ## Use Your Own Words | ||
|
|
||
| Write prose, including issue and pull request descriptions, documentation and code comments in your own words. Do not use automated tools to generate these for you. These artifacts are created to be read by humans, so we believe they should also be written by humans. |
There was a problem hiding this comment.
I'd like to point out again, that source code is also created to be read by humans. ("Programs must be written for people to read, and only incidentally for machines to execute" from SICP.)
Co-authored-by: Arman Bilge <arman@typelevel.org> Co-authored-by: Justin Reardon <me@jmreardon.com>
|
@durban , to respond to your comments in general, we are trying to draw a line between text written to explain code, and software code. The intention being that if the user can't describe the code themselves, they don't understand it well enough to responsibly open a PR. I'll see if I can wordsmith things better to be clear on that. |
5 participants
@samspills, it took me a bit to figure out a good way to fit this into the CoC, as the requirement (don't use AI prose) is negative, but the CoC focuses on positive actions. So it was hard for me to quite directly point out what we are asking. Any thoughts on that from @typelevel/coc would be appreciated. We will also need to update the actual CoC as well if we want to make this change.
@typelevel/board, I wrote the blog post with the foundation's voice seeing as this goes well beyond advice and also includes a code of conduct update. So your feedback and approvals would be greatly appreciated.
@typelevel/maintainers, this is the first draft of an actual contributing guide (see src/projects/contributing-guide.md) mentioned in typelevel/tsc#194 . I think they're pretty uncontroversial OSS contributing guidelines, and leave open the option of projects adding additional requirements. Feedback would be appreciated.
Screenshots to see for the calls to action look:
Added a horizontal rule for mobile, as the different button shapes made the layout look a little weird otherwise
