diff --git a/src/blog/contributing-guidelines-2026.md b/src/blog/contributing-guidelines-2026.md new file mode 100644 index 00000000..e6b3e68a --- /dev/null +++ b/src/blog/contributing-guidelines-2026.md @@ -0,0 +1,38 @@ +{% + author: ${foundation} + date: "2026-07-25" + tags: [governance] +%} + +# AI Tools, Contributing and Code of Conduct Updates + +## New Contributing Guide + +We have published a new [contributing guide](/projects/contributing-guide.md) for Typelevel organization projects and a [start contributing guide](/community/start-contributing.md) for new contributors! + +These guidelines cover similar ground to [the ones](/gsoc/ai.md) we have provided to Google Summer of Code applicants in the past. The new guide is an evergreen document to point any new contributor to for guidance. It covers where to start on an issue, copyright, and how to structure pull requests. + +## Code of Conduct Update + +We have also made a small addition to the [code of conduct](../code-of-conduct/README.md), adding a new behavior to the "Our Community" section: + +> - **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. + +## AI-related Policies + +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. + +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. + +### Use of Translation Tools + +We do understand that LLMs are excellent tools for bridging language barriers, and as always, we strive for the most inclusive environment possible on our projects and in our community spaces. To that end, we allow the use of AI tooling as a linguistic aid when English is not your primary language. Specifically, when you are authoring your own words in your own language and then leveraging a model to translate those words to English prior to posting in a Typelevel forum, this is considered acceptable and even encouraged behavior. + +This is very different from fully autonomous authorship of long-form prose. diff --git a/src/code-of-conduct/README.md b/src/code-of-conduct/README.md index 55ac9cbf..19f49102 100644 --- a/src/code-of-conduct/README.md +++ b/src/code-of-conduct/README.md @@ -20,7 +20,7 @@ Behaviors that reinforce these values contribute to a positive environment, and - **Being respectful.** We're respectful of others, their positions, their skills, their commitments, and their efforts. - **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. ## Our Standards @@ -77,6 +77,11 @@ For questions related to our code of conduct, or to report possible violations, * [Arman Bilge](mailto:arman@typelevel.org) * [Lucas Satabin](mailto:lucas.satabin@gnieh.org) +## Changelog + +* March 8, 2024: Initial version. +* August 3, 2026: "Using your own words" behavior added. + ## Attribution This code of conduct is a modified version of the [Python Software Foundation Code of Conduct](https://www.python.org/psf/conduct), licensed under the [Creative Commons Attribution-ShareAlike 3.0 Unported License](https://creativecommons.org/licenses/by-sa/3.0/). diff --git a/src/colophon.md b/src/colophon.md index 7b17fb8d..707b3338 100644 --- a/src/colophon.md +++ b/src/colophon.md @@ -25,7 +25,8 @@ In general, the content on this website is licensed under the [Creative Commons Blog posts written before 2026 are licensed under the [Creative Commons Attribution 3.0 Unported License][CC BY 3.0]. -The Typelevel logo is adapted from the ["Progress" Pride Flag][progress] by [Daniel Quasar] and licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License][CC BY-NC-SA 4.0]. +The Contributing to Typelevel Projects guide is adapted from the [Godot Pull request rules and guidelines](https://github.com/godotengine/godot-contributing-docs/blob/f46474c855c36883b61d0438414365c771ea78dd/pull_requests/pull_request_guidelines.rst) by the Godot Engine Contributors and licensed under the [Creative Commons Attribution 3.0 Unported License][CC BY 3.0]. + [contributors]: https://github.com/typelevel/typelevel.github.com/graphs/contributors [CC BY 4.0]: https://creativecommons.org/licenses/by/4.0/ diff --git a/src/community/start-contributing.md b/src/community/start-contributing.md index f8917847..b5fb59b2 100644 --- a/src/community/start-contributing.md +++ b/src/community/start-contributing.md @@ -3,6 +3,7 @@ Typelevel projects power a large part of the functional Scala ecosystem. They are also complex, long-lived codebases with active communities. Contributing can feel intimidating at first, but even bug reports, small fixes, and documentation updates help move our projects forward! +See also the [Contributing to Typelevel Projects](../projects/contributing-guide.md) for a detailed explanation of our contribution policies. **Become a user of the ecosystem you want to contribute to.** @@ -30,7 +31,7 @@ Typelevel projects power a large part of the functional Scala ecosystem. They ar **Open a PR and iterate** - Fork the repo, create a branch, and implement the change. Add or update tests where appropriate. -- Open a PR with a clear description of the problem and your solution. +- Open a PR with a clear description of the problem and your solution. Read the [Contributing to Typelevel Projects](../projects/contributing-guide.md) guide. - Expect review feedback, ask questions, adjust your changes, and iterate. ## Where to Ask for Help diff --git a/src/projects/README.md b/src/projects/README.md index 422f8644..9a6c9109 100644 --- a/src/projects/README.md +++ b/src/projects/README.md @@ -1,3 +1,4 @@ {% laika.title: Typelevel Projects + laika.html.template = projects.template.html %} diff --git a/src/projects/contributing-guide.md b/src/projects/contributing-guide.md new file mode 100644 index 00000000..1f755c7b --- /dev/null +++ b/src/projects/contributing-guide.md @@ -0,0 +1,92 @@ +# Contributing to Typelevel Projects + +These guidelines apply when contributing to any Typelevel organization project. Please also refer to individual project guidelines for additional guidelines. + +Typelevel affiliate projects are also welcome to integrate these guidelines into their contributing guidelines. + +> This document focuses on policy. See also the [Start Contributing](../community/start-contributing.md) guide if you want step-by-step guidance on contributing to Typelevel projects. + +Welcome to the Contributing to Typelevel Projects guide. This document provides an overview of Typelevel's expectations when contributing to organization projects. At a very high level: + +We **want** contributors who are interested in gaining a deeper understanding of the projects they're working on, learning how and why they were built, and working with the community to improve our projects. + +We do **not** want contributors that increase the workload for maintainers without any gain for the project or any learning for the contributor. + +The following sections provide guidance on how to make contributions that fall into the first category. + + +## Respect our Code of Conduct + +When you contribute to Typelevel, we expect that you respect our [Code of Conduct](/code-of-conduct/README.md). + +## 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. + +While Typelevel communications are primarily conducted in English, our contributors and users are worldwide and may not be proficient in written English. Using machine translation tools (including LLM translation tools) to translate your writing to English is always acceptable. You may also include the original text in your message. + +## 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. + +When you are reporting a bug, your issue should clearly state the expected versus actual behavior you are observing. An ideal bug report includes a minimal reproducer that can easily be run (e.g. a scala-cli script, a small repository, or a saved Scastie) to demonstrate the issue. When you are unable to do so, please provide what other information you can, for example: specific steps that caused the issue, stack traces, or error messages. + +When you are reporting a security issue, *do not* open a Github issue. See the project security policy or the [Typelevel security policy](/security.md). + +## Pull Requests + +The following guidelines are particularly relevant for pull requests: + +### Respect Copyright + +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. + +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. + +"Source-available" is **not** "open-source", and not all open-source licenses are compatible with each other. We strongly recommend against reading any "source-available" or incompatibly-licensed code before contributing to Typelevel projects. + +### Contribute One Change at a Time + +Each pull request should contain a single self-contained change. Avoid pushing multiple unrelated changes in the same pull request. + +As a rule of thumb, if your pull request could be split into two pull requests without breaking anything, it should probably be two separate pull requests. + +The exception to this rule is "batching changes", where you make the same kind of change to multiple places in the codebase. In this case, it is preferable to make one larger pull request instead of many small ones. + +> **Note:** Imagine yourself in the shoes of the reviewer: how can you make the PR easy to review and approve? +> +> This is best achieved if your pull request is simple, coherent, and uncontroversial. +> +> Limiting pull requests to one change at a time also simplifies the Git history, makes it possible to revert or cherry-pick specific changes, and reduces the potential of accidentally introducing bugs. + +### Explain Your Contributions + +When submitting a pull request, please make use of the pull request description. + +Your pull request description should, as clearly and succinctly as possible, in your own words, explain all the necessary information to understand the changes you made. + +For example, if you're just fixing a typo, a single sentence description is appropriate. However, if your change is large, we expect you to be more thorough with your explanation. + +Here are the components of a thorough pull request description: + +- **Summary of changes:** A short overview of what is changed. +- **Motivation:** Why you opened the pull request. Ideally, this is a link to an issue. +- **Related work:** Link to similar pull requests or ongoing discussions that provide additional context. +- **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. + +> **Note:** You may not need *every* one of these components, and you do not need to copy this exact structure. Always ask yourself what would be most helpful for reviewers, and try to balance brevity and thoroughness appropriately. + +### Contribute Only What You Stand Behind + +Only submit code that you understand, are prepared to explain to a maintainer, and be responsible for. + +This especially applies if you implement the idea of another person, copy code from elsewhere, or if you use AI to assist you with your contribution. In all of these cases, you must disclose which part of your submission wasn't fully authored by you. Regardless of the code's origin, by opening a pull request, you are putting your reputation as a contributor behind the code. + +--- + +This document is based on the [Godot Pull request rules and guidelines](https://github.com/godotengine/godot-contributing-docs/blob/f46474c855c36883b61d0438414365c771ea78dd/pull_requests/pull_request_guidelines.rst) by the Godot Engine Contributors and is licensed under the [CC BY 3.0 license](https://creativecommons.org/licenses/by/3.0/deed.en). diff --git a/src/projects/default.template.html b/src/projects/projects.template.html similarity index 93% rename from src/projects/default.template.html rename to src/projects/projects.template.html index b0ad82ac..a8cbd263 100644 --- a/src/projects/default.template.html +++ b/src/projects/projects.template.html @@ -13,6 +13,13 @@

Typelevel Projects

community guidelines. While not directly supported by the Foundation, these projects are designed to be compatible with the overall Typelevel ecosystem.

+

Contributing

+
+

If you are interested in contributing to Typelevel projects, see the + Contributing to Typelevel Projects guidelines. +

+
+

Organization Projects