From c06693d32c1c6db42d2c7f4e297575c807a9f3b3 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Sun, 23 Jun 2024 19:42:00 +0530 Subject: [PATCH 1/3] Initial draft --- docs/maintainers-guide.md | 59 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/maintainers-guide.md diff --git a/docs/maintainers-guide.md b/docs/maintainers-guide.md new file mode 100644 index 00000000..8052f8e8 --- /dev/null +++ b/docs/maintainers-guide.md @@ -0,0 +1,59 @@ +# Maintainers Guide + +This page offers guidance to project maintainers regarding our setup procedures, release processes, package creation, and other related tasks. + +# Maintainer Onboarding and Best Practices + +## Becoming a Maintainer or Triager + +If you are interested in becoming a maintainer, you can join our community. We expect you to be actively involved. + +Also, if you're interested in helping managing issues with labels and interacting with incoming requests, you can have a "triager" role! + +## Maintainer Responsibilities and Expectations + +1. As a maintainer, there is no strict time obligation, as we understand that everyone's ability to commit can fluctuate. However, we do expect maintainers to communicate openly and transparently with the team and the community. + +2. As a maintainer, you are expected to uphold a positive and inclusive team culture. This includes following the guidelines outlined in the [Openscapes team culture page](https://openscapes.github.io/series/core-lessons/team-culture.html) and the [recorded psychological safety talk](https://www.youtube.com/watch?v=rzi-qkl8u5M) . By doing so, you can help ensure that all team members and contributors feel safe, respected, and valued. + + +## Maintainer Processes Beyond Regular Contributing + +1. As a maintainer, label issues clearly and consistently to help contributors identify issue types and priority. Use 'good first issue' for contributor-friendly issues. + +2. As a maintainer, create welcoming environment when communicating with contributors (issue / PR / discussion posters). + +3. As a maintainer reviewing and merging contributions is critical. Here are some best practices: + + 3a. Review contributions thoroughly. + + 3b. Provide constructive feedback. + + 3c. Communicate clearly and respectfully. + + 3d. Merge contributions promptly. + +4. As a maintainer, you will be releasing different versions. More on this in [here](#making-a-release). + +# Branches + +main: This is the main branch, which is consistently tested and prepared for release as a new version. Avoid pushing changes directly to this branch. Instead, create a new branch and submit a pull request for any modifications. + +gh-pages: This branch hosts HTML docs, updated by GitHub Actions. Don't commit directly. Make changes in a separate branch, then submit a pull request. GitHub Actions will automatically update docs on gh-pages when merged. + +# Continuous Integration + +The GitHub Actions CI services handle the project's building, testing, and management across Linux, macOS, and Windows platforms. The CI file manages the continuous integration processes, and list out their respective dependencies. Here we briefly summarize the functions of the files in CI. + +```environment-dev.yml ``` - The environment configuration file specifies dependencies for Python development. + +```environment-mindeps.yaml``` - The test-environment file lists required and test dependencies for a testing environment. + +# Continuous Documentation + +The Read the Docs service is used to preview documentation changes made in pull requests. This service uses a configuration file, ```.readthedocs.yaml```. + +# Making a Release + +To automate releases, we employ a script called ```publish.sh``` in the scripts folder. This script utilizes Poetry for managing and publishing the package to PyPI. + From b4d27f7e407c56eeb432f9e31ccf7e94abcb8e0a Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Mon, 24 Jun 2024 13:38:21 +0530 Subject: [PATCH 2/3] Made the discusssed changes --- docs/maintainers-guide.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/maintainers-guide.md b/docs/maintainers-guide.md index 8052f8e8..123a6f6c 100644 --- a/docs/maintainers-guide.md +++ b/docs/maintainers-guide.md @@ -2,22 +2,24 @@ This page offers guidance to project maintainers regarding our setup procedures, release processes, package creation, and other related tasks. -# Maintainer Onboarding and Best Practices +## Maintainer Onboarding and Best Practices -## Becoming a Maintainer or Triager +### Becoming a Maintainer or Triager -If you are interested in becoming a maintainer, you can join our community. We expect you to be actively involved. +If you are interested in becoming a maintainer, you can join our community. Maintainers have several important responsibilities, so please read on to understand the role. Also, if you're interested in helping managing issues with labels and interacting with incoming requests, you can have a "triager" role! -## Maintainer Responsibilities and Expectations +To get permissions, please start by participating on GitHub by answering questions, reviewing PRs, or contributing code or documentation. Once you're feeling comfortable, you can ask any of our maintainers for permissions by `@`ing them on GitHub. + +### Maintainer Responsibilities and Expectations 1. As a maintainer, there is no strict time obligation, as we understand that everyone's ability to commit can fluctuate. However, we do expect maintainers to communicate openly and transparently with the team and the community. 2. As a maintainer, you are expected to uphold a positive and inclusive team culture. This includes following the guidelines outlined in the [Openscapes team culture page](https://openscapes.github.io/series/core-lessons/team-culture.html) and the [recorded psychological safety talk](https://www.youtube.com/watch?v=rzi-qkl8u5M) . By doing so, you can help ensure that all team members and contributors feel safe, respected, and valued. -## Maintainer Processes Beyond Regular Contributing +### Maintainer Processes Beyond Regular Contributing 1. As a maintainer, label issues clearly and consistently to help contributors identify issue types and priority. Use 'good first issue' for contributor-friendly issues. @@ -33,27 +35,24 @@ Also, if you're interested in helping managing issues with labels and interactin 3d. Merge contributions promptly. -4. As a maintainer, you will be releasing different versions. More on this in [here](#making-a-release). +4. As a maintainer, you will be releasing different versions. More on this in [here](./contributing/releasing.md). -# Branches +## Branches main: This is the main branch, which is consistently tested and prepared for release as a new version. Avoid pushing changes directly to this branch. Instead, create a new branch and submit a pull request for any modifications. -gh-pages: This branch hosts HTML docs, updated by GitHub Actions. Don't commit directly. Make changes in a separate branch, then submit a pull request. GitHub Actions will automatically update docs on gh-pages when merged. -# Continuous Integration +## Continuous Integration & Delivery -The GitHub Actions CI services handle the project's building, testing, and management across Linux, macOS, and Windows platforms. The CI file manages the continuous integration processes, and list out their respective dependencies. Here we briefly summarize the functions of the files in CI. +The GitHub Actions CI services handle the project's building, testing, and management across Linux, macOS, and Windows platforms. The CI files can be found in the `./.github/workflows/` which manage the continuous integration process, the dependencies are listed out in the `./ci/environment-dev.yml` file. Here we briefly summarize the functions of the files in the `./ci/` directory. -```environment-dev.yml ``` - The environment configuration file specifies dependencies for Python development. +`environment-dev.yml` - The environment configuration file specifies dependencies for Python development. -```environment-mindeps.yaml``` - The test-environment file lists required and test dependencies for a testing environment. +`environment-mindeps.yaml`- Specifies an environment with the minimum supported dependency versions to detect backwards-incompatible code. -# Continuous Documentation +## Continuous Documentation -The Read the Docs service is used to preview documentation changes made in pull requests. This service uses a configuration file, ```.readthedocs.yaml```. +[ReadTheDocs](https://readthedocs.org/projects/earthaccess/) is used to generate and host [our documentation website](https://earthaccess.readthedocs.io/) as well as the preview for documentation changes made in pull requests. This service uses a configuration file in the root of the project, `.readthedocs.yml`. -# Making a Release -To automate releases, we employ a script called ```publish.sh``` in the scripts folder. This script utilizes Poetry for managing and publishing the package to PyPI. From 0fe3a16b122aeb9876107cac7734f2d34dd32440 Mon Sep 17 00:00:00 2001 From: Sherwin-14 Date: Tue, 25 Jun 2024 13:48:03 +0530 Subject: [PATCH 3/3] Added to the work with us section --- docs/{ => contributing}/maintainers-guide.md | 4 ++-- mkdocs.yml | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) rename docs/{ => contributing}/maintainers-guide.md (91%) diff --git a/docs/maintainers-guide.md b/docs/contributing/maintainers-guide.md similarity index 91% rename from docs/maintainers-guide.md rename to docs/contributing/maintainers-guide.md index 123a6f6c..1ac2fc79 100644 --- a/docs/maintainers-guide.md +++ b/docs/contributing/maintainers-guide.md @@ -35,7 +35,7 @@ To get permissions, please start by participating on GitHub by answering questio 3d. Merge contributions promptly. -4. As a maintainer, you will be releasing different versions. More on this in [here](./contributing/releasing.md). +4. As a maintainer, you will be releasing different versions. More on this in [here](./releasing.md). ## Branches @@ -44,7 +44,7 @@ main: This is the main branch, which is consistently tested and prepared for rel ## Continuous Integration & Delivery -The GitHub Actions CI services handle the project's building, testing, and management across Linux, macOS, and Windows platforms. The CI files can be found in the `./.github/workflows/` which manage the continuous integration process, the dependencies are listed out in the `./ci/environment-dev.yml` file. Here we briefly summarize the functions of the files in the `./ci/` directory. +The GitHub Actions CI services handle the project's building, testing, and management across Linux, macOS, and Windows platforms. The CI configuration files can be found in the `./.github/workflows/`. Here we briefly summarize the functions of the files in the `./ci/` directory. `environment-dev.yml` - The environment configuration file specifies dependencies for Python development. diff --git a/mkdocs.yml b/mkdocs.yml index 579e0787..14317502 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,6 +60,8 @@ nav: - "Development": "contributing/development.md" - "Releasing": "contributing/releasing.md" - "Our meet-ups": "contributing/our-meet-ups.md" + + - "Maintainers Guide": "contributing/maintainers-guide.md" - "Resources": "resources.md" - USER GUIDE: - "user_guide/index.md"