From ef66e370297a31e89d673e17b89991ae135662e1 Mon Sep 17 00:00:00 2001 From: Fridolin Glatter <83776373+glatterf42@users.noreply.github.com> Date: Wed, 11 Sep 2024 17:45:25 +0200 Subject: [PATCH] Improve GitHub community standards (#871) * Add security policy * Add code of conduct * Add contributing guidelines * Add guidelines for getting support * Leave out google group intentionally to centralize information * Finalize support guidelines * Add governance guidelines * Address review comments * Include new information in docs landing page * Add Contributor Covenance badge * Mention community guidelines in release notes --- .github/CONTRIBUTING.md | 5 ++ .github/SECURITY.md | 23 ++++++++ CODE_OF_CONDUCT.md | 128 ++++++++++++++++++++++++++++++++++++++++ GOVERNANCE.md | 31 ++++++++++ README.md | 9 +++ RELEASE_NOTES.rst | 10 +++- SUPPORT.md | 44 ++++++++++++++ doc/index.rst | 7 +++ 8 files changed, 255 insertions(+), 2 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/SECURITY.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 GOVERNANCE.md create mode 100644 SUPPORT.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..e1573c45f --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,5 @@ +# Contributing + +Thank you for wanting to contribute to `message_ix`! +We highly value your input. +Please refer to [our contributing guidelines](https://docs.messageix.org/en/latest/contributing.html) to learn about how to contribute to our community. diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 000000000..ea4270302 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,23 @@ +# Security Policy + +As careful and community-oriented maintainers, we strive to keep our code safe to use for everyone. +For this purpose, we highly value your input and will acknowledge your contributions as best we can. + +## Supported Versions + +Unfortunately, the resources available for maintaining `message_ix` do not allow us to: + +- Support multiple versions at once. +- Publish maintenance updates for older versions. For example, once `message_ix` version 3.10 is released, no further patch versions like 3.8.x, 3.9.x, etc. are possible. + +We generally develop our `main` branch and so to get the version of our code that contains all currently available security updates, please [install our code from source](https://docs.messageix.org/en/latest/install-adv.html#install-from-github) using the `main` branch. +Please reach out to us if you encounter any issues in doing so. + +If this is not an option, please ensure you are using the [latest release of our code](https://github.com/iiasa/message_ix/releases) to profit from as many security updates as possible. +`message_ix` is generally released twice a year, but may make additional releases on a shorter time line if necessary to mitigate critical vulnerabilities. + +## Reporting a Vulnerability + +To report a security issue, please use the GitHub Security Adivsory ["Report a vulnerability"](https://github.com/iiasa/message_ix/security/advisories/new) tab. +We will try to respond to your report as soon as possible with our and your next steps. +If you wish, we will keep you informed about any progress until the vulnerability is fixed. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..031f5ea69 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +glatter `` iiasa.ac.at or kishimot `` iiasa.ac.at. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. \ No newline at end of file diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 000000000..a44a0fb42 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,31 @@ +# Governance + +The `message_ix` team welcomes contributions of any kind from anyone! +If you are looking to understand how the team operates and how we decide what to do with your contributions, please read on. + +Decisions in the `message_ix` framework are made following good scientific practice, that is, only after careful discussion and review from at least another colleague. +Depending on the size of the impact the decision will likely have, different scales of decision making are employed. +For small decisions, the decision may be handled by the [maintainers](#maintainers), while for larger decisions, discussion in the [weekly team meetings](#weekly-team-meetings) may be required. + +## Maintainers + +At the moment, `message_ix` is maintained by @khaeru and @glatterf42. +This mostly means that they are most active in responding to issues and discussions and perform the housekeeping work as it arises. +However, given the size of the `message_ix` framework, it is all but impossible to be truly familiar with every aspect of it. +For this reason, incoming questions may also be answered by various [specialists within our team](#specialists). + +## Specialists + +The `message_ix` framework covers many topics already and can be expanded to cover many more and coupled to various other scientific software. +Examples of this include the modules for water, buildings, material, and transport, or land-use emulators such as [MAgPIE](https://www.pik-potsdam.de/en/institute/departments/activities/land-use-modelling/magpie). +For all these topics, individual specialists within our team collaborate with one another. +We encourage everyone to use [trunk-based development](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development) and [GitHub projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) to develop their individual version of our code, while maintaining compatibility with other version. +We then encourage everyone to frequenly bring their changes to our code back to our `main` development branch. + +## Weekly Team Meetings + +Every Thursday, the `message_ix` core developer team meets to discuss current developments. +This includes discussing proposed changes to the core formulation or new feature ideas in detail. + +Once a month, this meeting is extended to invite everyone at IIASA with an interest in `message_ix`. +These meetings serve the purpose of giving a high-level overview as well as receiving feedback from people who do not join the other meetings. diff --git a/README.md b/README.md index 4cac9fe4c..89300bb07 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ [![Documentation build](https://readthedocs.com/projects/iiasa-energy-program-message-ix/badge/?version=stable)](https://docs.messageix.org/en/stable/) [![Build status](https://github.com/iiasa/message_ix/actions/workflows/pytest.yaml/badge.svg)](https://github.com/iiasa/message_ix/actions/workflows/pytest.yaml) [![Test coverage](https://codecov.io/gh/iiasa/message_ix/branch/main/graph/badge.svg)](https://codecov.io/gh/iiasa/message_ix) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) MESSAGEix is a versatile, dynamic, model framework for energy-engineering-economy-environment (E4) systems research. @@ -44,6 +45,14 @@ Other forms of documentation: - For offline use, the documentation can be built from the source code. See the file [`doc/README.rst`](doc/README.rst) +## Commitment to our Community + +- We aim to create a community that is welcoming to everyone. Please respect our [Code of Conduct](CODE_OF_CONDUCT.md) at all times when interacting with `message_ix` and the community. +- We warmly welcome all contributions to our community. Please take a look at our [guidelines for contributing to development](https://docs.messageix.org/en/latest/contributing.html). +- If you are looking to understand how the `message_ix` team operates and how we decide what to do with your contributions, please read our [governance guidelines](GOVERNANCE.md). +- We highly value code security. To learn more about our security practice and advice, please visit our [security policy](.github/SECURITY.md). +- We strive to entertain a welcoming and inclusive community. If you struggle to use `message_ix`, please check our [guidelines for getting support](SUPPORT.md). + ## License Copyright © 2018–2024 IIASA Energy, Climate, and Environment (ECE) Program diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst index 343842148..afe4c1a65 100644 --- a/RELEASE_NOTES.rst +++ b/RELEASE_NOTES.rst @@ -1,5 +1,11 @@ -.. Next release -.. ============ +Next release +============ + +GitHub community guidelines +--------------------------- + +Add community guidelines for interaction on GitHub (:pull:`871`). +Please familiarize yourself with these to foster an open and welcoming community! .. All changes .. ----------- diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 000000000..62be4d327 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,44 @@ +# Getting Support + +We are glad that you want to use `message_ix` and sorry to hear that you are running into issues! +This page aims to showcase various ways to get support for when you feel stuck. + +If you want to learn more about how `message_ix` works, from the ideas behind it to the meanings of every single parameter, please refer to [our documentation](#our-documentation) first. + +If you conclude that these are not enough and you have a specific question, please check if [our GitHub discussions](#github-discussions) have got you covered. + +If you encounter an issue using `message_ix` as you envisioned, please let us know using [our GitHub issues](#github-issues). + +If you have exhausted all previous options *and* collaborate with IIASA, you may also reach out to us on [Slack](#slack). + +## Our Documentation + +We offer extensive documentation for how `message_ix` works and encourage all new contributions to provide new documentation, too. +Please find our documentation at https://docs.messageix.org/. +Please note the search bar on the left side, and try to use it! +It is a fast and reliable way to find what you are looking for. + +## GitHub Discussions + +We always welcome new discussion posts on GitHub. +Collecting them all in one place allows other users to find and interact with existing discussions rather than all having to start from scratch. +Please visit https://github.com/iiasa/message_ix/discussions for a list of all past discussions. +You can search them for keywords or scroll through them by category. +If you don't find your particular point of interest addressed already, please [start a new discussion](https://github.com/iiasa/message_ix/discussions/new/choose) by selecting the category that you think is fitting. +We strive to answer as quickly as we can, but may take a few days to get back to you if we are extremely pre-occupied. +Please come back to any discussion you opened to select the answer that finally helped you solve your question. + +## GitHub Issues + +We appreciate your efforts to tell us that something is not working as intended! +Please head over to https://github.com/iiasa/message_ix/issues and search the existing issues to see if your issue has already been reported. +If no one encountered it before you, please [open a new issue](https://github.com/iiasa/message_ix/issues/new/choose) by completing the form as best you can. +We strive to respond as quickly as we can, but may take a few days to get back to you if we are extremely pre-occupied. + +## Slack + +This option is only available if you collaborate with IIASA in one form or the other. +And even then, it should only be used after the other resources have been exhausted. +Ask your collaboration contact at IIASA to invite you to Slack, if they have not done so already. +On Slack, please navigate to the `message` "External Connection" in the "IIASA ECE Program". +There, you can search past posts, or post your new topic as usual. diff --git a/doc/index.rst b/doc/index.rst index 9430c06fe..2ec50e045 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -112,12 +112,17 @@ Using, getting help, and contributing Everyone is encouraged to use the framework to develop energy system and integrated assessment models! +Everyone is required to please follow our Code of Conduct, which you can find `on GitHub `__ or in :file:`CODE_OF_CONDUCT.md` included with the source code. + - :doc:`api` - :doc:`rmessageix` - :doc:`whatsnew` —release history and migration/upgrade notes. - :doc:`notice` —including how to properly cite the framework and software in scientific research. + - :doc:`contributing` —we welcome enhancements to the framework itself that enable new features across all models. +- You can learn more about how we handle your contributions `on GitHub `__ or in :file:`GOVERNANCE.md` included with the source code. - :doc:`sharing`—we invite the sharing of the usage of the |MESSAGEix| framework. +- See our Security Policy `on GitHub `__ or in :file:`.github/SECURITY.md` included with the source code. - :doc:`faq` - :doc:`bibliography` @@ -130,7 +135,9 @@ Everyone is encouraged to use the framework to develop energy system and integra whatsnew notice contributing + governance sharing + security policy faq bibliography