Skip to content

Commit

Permalink
more rearranging of words and issue template for maintainer application
Browse files Browse the repository at this point in the history
  • Loading branch information
@JustinGOSSES
JustinGOSSES committed Dec 21, 2023
1 parent 02c011e commit 48076b7
Show file tree
Hide file tree
Showing 3 changed files with 145 additions and 93 deletions.
42 changes: 42 additions & 0 deletions .github/ISSUE_TEMPLATE/maintainer_application.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
name: Mainainer Application
description: Mainainer Application
title: "[Maintainer]: "
labels: ["triage"]
assignees:
- awesome
body:
- type: markdown
attributes:
value: |
Thanks for volunteering to be a maintainer of this repository!
- type: input
id: contact
attributes:
label: Contact Details
description: How can we get in touch with you if we need more info?
placeholder: ex. [email protected]
validations:
required: false
- type: textarea
id: Why
attributes:
label: Why
description: Why do you want to be a maintainer?
placeholder: Want to learn maintainer skills, Want to keep this list growing, etc.
value: "Want to learn maintainer skills."
validations:
required: true
- type: textarea
id: participation
attributes:
label: How have you participated
description: How have you participated in this repository, the Software Underground, or other geoscience related communities. Doesn't need to be long or elaborate.
render: shell
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
options:
- label: I agree to follow this project's Code of Conduct
required: true
3 changes: 1 addition & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,10 @@
> Geoscience is [awesome](awesome.md).
[![Awesome](https://raw.githubusercontent.com/softwareunderground/awesome-open-geoscience/master/media/icon/badge.svg)](https://github.com/sindresorhus/awesome) [![.github/workflows/link_checker.yml](https://github.com/softwareunderground/awesome-open-geoscience/actions/workflows/link_checker.yml/badge.svg)](https://github.com/softwareunderground/awesome-open-geoscience/actions/workflows/link_checker.yml) [![Contributions](https://img.shields.io/github/issues-pr-closed-raw/softwareunderground/awesome-open-geoscience.svg?label=contributions)](https://github.com/softwareunderground/awesome-open-geoscience/pulls) [![Commits](https://img.shields.io/github/last-commit/softwareunderground/awesome-open-geoscience.svg?label=last%20contribution)](https://github.com/softwareunderground/awesome-open-geoscience/commits/main) [![Chat on slack](https://img.shields.io/badge/slack-join-ff69b4.svg)](https://swung.slack.com/join/shared_invite/enQtNTczNjM4ODMxODMwLTQ3Yjk3MjFmOTJkYzUyZDU3OGI3ZmJhMzIyNzQxYjcyZDM5MWU4OTVmNTBiOTM4Zjg1ZDViOGM3NmQ4OTgzOTk) [![License](https://img.shields.io/github/license/softwareunderground/awesome-open-geoscience.svg)](https://github.com/softwareunderground/awesome-open-geoscience/blob/master/LICENSE)


[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8354180.svg)](https://zenodo.org/records/8354180)

Open geoscience is even more awesome, so we made a list. This list is curated from repositories that make our lives as geoscientists, hackers and data wranglers easier or just more awesome. In accordance with the awesome manifesto, we add awesome repositories. We are open to [contributions](contributing.md) of course, this is a community effort after all.
If you are interested in being a maintainer of this repository, leave the [maintainer role](/maintainerRole.md) file.

## Contents

Expand Down
193 changes: 102 additions & 91 deletions maintainerRole.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,74 +2,131 @@

This document provides an overview of how to be a maintainer for this repository.

## Goals
## Maintainer goals

_The goal for maintainers should be for contributors to have a good experience
adding to the Awesome list._

The goal for maintainers should be for contributors to have a good experience
adding to the Awesome list.
New potential contributors should be able to look at the
record of past experiences in closed pull requests and be encouraged by what
they see to add their own contributions.

If a contribution is lacking in some manner that leads to it falling short
of being "AWESOME", clear feedback should be given
with a pleasant and positive framing. Often this can lead to improvements
in projects, additional documentation that helps users, etc. All good things.

Rarely, a contribution will not be merged due to sustained shortcomings.
This is okay too. Maintaining the minimum bar helps ensure the consumers of
the list find value in it and some of them eventually add their own
contributions.

## Tasks
## Who, How, and Why be a maintainer of this repository?

### Who can be a maintainer?

Anyone who has any participation in the Software Underground
Slack/Mattermost discussions or has made contribution(s) to this repository
can become a maintainer if they want.

### How to become a maintainer?

Anyone added to the
[awesome GitHub team](https://github.com/orgs/softwareunderground/teams/awesome)
will have effectively have permissions that let them do maintainer tasks
like approve pull requests.

To join that list of maintainers, add an issue to this repository.
Select the issue template called "maintainer_application"
and ping all the members of the
[awesome GitHub team](https://github.com/orgs/softwareunderground/teams/awesome)
like ` @justinGOSSES , @leouieda, etc.` after you submit the issue in a secondary
comment to the issue.
One of them will reach our and/or add you to the
[awesome GitHub team](https://github.com/orgs/softwareunderground/teams/awesome).

### Why be a maintainer?

Historically, most of the maintainers who approve issues on this repository
where involved in setting up the repository.
We would like to broaden the participation.

#### Gain maintainership skills

Being a mainter on a repository like this is a great opportunity to
learn maintainer skills and to do so in a low risk situation.
Solving merge conflicts, managing community members, and lowering friction
for developers are all important skills for working on open source
code repositories. This repository is merely a list, so the stakes
are low. There is no production service to break or be "down".

#### Put it on your resume

While the stakes are low, the impact is high.
This repository is one of the most starred repositories on GitHub
under the 'geoscience' topic, Being a maintainer on this resume
is something that one can list on
their resume as evidence of contributing to the open source geoscience
community and evidence of their experience solving merge conflicts,
working with external contributors, etc.

#### Work with a net

Typical maintainer tasks for this repository include approving pull requests,
submitting their own contributions like everyone else, and handling
questions about new features.
If you have questions as a new maintainer, there are
experienced people you can reach out to for advice.
For example, you can send a private message to JustinGOSSES
in the Software Underground [mattermost channel](https://softwareunderground.org/mattermost)
if you have a question.

## Maintainer tasks

### Approving Pull Requests

The bulk of the maintainers task is about approving pull requests.
The most common maintainer tasks is evaluating and approving pull requests.

#### When to approve an item as "Awesome" that has been submitted in a pull request

The characteristics that are required to be an "awesome" open source geoscience
resource is described in the [contributing.md](/contributing.md)
and [awesome.md](/awesome.md) files.

Additionally, there are cases where a maintainer will want to attempt to
run a program mentioned in a pull request themselves.
This is not always required, but
sometimes seems appropriate if the "installation" or "how to use"
instructions are sparse or suggestive of a single operating system.
In the past, this has caught
issues that prevented new users from using the project who work on a different
operating system than the contriutor.
and [awesome.md](/awesome.md) files. A checklist gets
generated via
the [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md).

Most of the process of evaluating a
contribution to the awesome list is just checking
off that all these criteria are satisfied.
Many pull request approvals are straight forward and takes 5-12 minutes.

In some cases, a maintainer may want to attempt to
run a program mentioned in a pull request themselves. This takes more time.
A maintainer might want to do this if there are signs in the
the installation instructions or files that the application
might only run on the originators computer or operating system.
In the past, these sorts of problems have been identified
and fixed.

#### Debugging pull request conflicts

Sometimes there are competing pull requests that conflict with one another.
This can require a maintainer to resolve the merge conflict.
Rarely there are multiple pull requests in the que that
impact the same lines in some file causing a merge conflict.
For instructions on how to "fix merge conflict" on the web interface for
GitHub see
[GitHub's fixing merge conflict guidelines](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github)

#### CI/CD Automation test failture

Please read the ["How to fix automation problems"](contributing.md/#how-to-fix-automation-problems) for instructions on how to fix problems
related to the TravisCI continuous improvement tooling that runs with
each pull request.
Please read the ["How to fix automation problems"](contributing.md/#how-to-fix-automation-problems) for instructions on how to fix
previously seen problems related to the TravisCI continuous improvement
tooling that runs with each pull request.

The most common reason for a pull request to not be immediately
mergable is a failure in the Travis CI (continuous integration)
script related to links in the README.md.
Links that used to work can 404 or redirect from their original
URL to a new URL. In both cases, this will cause the CI to fail.

To fix these issues, use a search engine
to look for a new link address if it exists.
to look for a new link address. If a new URL exists, then edit
the README.md file directly in the pull request with the new link address.
If that resource being linked to has disappeared entirely, it
may mean its time to delete a previous contribution that includes the link.

may mean it is time to delete the previous contribution that includes the link.
It is often easiest to do these types of fixes using the
"edit this file" button as described in
the [contributing.md](/contributing.md) file.
Expand All @@ -81,73 +138,27 @@ This has included new sections, like datasets, as well as a request
for a DOI for the awesome list repository.
These conversations mostly take place in issues. For longer conversations
or for expanding the scope of who is included, it can also be useful
to post a question on the "Open Geoscience" channel in the Software Underground mattermost channel.

## How responsive do maintainers need to be?

Faster is always better as it makes people feel more included to get
a fast response, but traditionally this repository has been
managed in a very asynchronous manner with pull requests often getting
responses in 1-2 week range and sometimes unfortunately significantly longer.
We should probably try to reduce this time to first response.

## Who, How, and Why be a maintainer of this repository?

### Who can be a maintainer?

Anyone how has a record of participation in the Software Underground
Slack/Mattermost discussions or has made contributions to this repository
can become a maintainer if they want.

### How to become a maintainer?

Anyone added to the
[awesome GitHub team](https://github.com/orgs/softwareunderground/teams/awesome)
has maintainer permissions that let them approve pull requests.
to post a question on the "Open Geoscience" channel in the
Software Underground [mattermost channel](https://softwareunderground.org/mattermost).

To become a maintainer, add an issue to this repository.
Select the issue template called "maintainer_application"
and ping all the members of the
[awesome GitHub team](https://github.com/orgs/softwareunderground/teams/awesome)
like ` @justinGOSSES , @leouieda, etc.` after you submit the issue.
One of them will reach our and/or add you to the
[awesome GitHub team](https://github.com/orgs/softwareunderground/teams/awesome).
### Maintainers should respond to new issues and pull requests

#### Keeping track of new issues and pull requests
To be a maintainer, you just need to make a good faith effort to
Maintainers should make a good faith effort to
respond to new issues and pull requests on this repository.
Once you are a maintainer, it is recommended, you click the
Once you are a maintainer, it is recommended that you click the
watch button right next to the fork button the main page of the
[repository](https://github.com/softwareunderground/awesome-open-geoscience)
This will put any new issues or pull requests you haven't visited
in your GitHub noticiations que.

You'll also likely want to make use of the GitHub notification page if you
don't already. A direct link to new issues and pull requests limited to
This will put any new issues or pull requests you haven't already visited
in your GitHub noticiations que.
A direct link to new issues and pull requests limited to
this repositories is [https://github.com/notifications?query=repo%3Asoftwareunderground%2Fawesome-open-geoscience](https://github.com/notifications?query=repo%3Asoftwareunderground%2Fawesome-open-geoscience)
If you don't visit the GitHub notifications page often, you might want
to set a reminder to double check nothing has been missed.

### Why be a maintainer?

Historically, most of the maintainers who approve issues on this repository
where involved in setting up the repository.
We would like to broaden the participation.

#### Gain maintainership skills
Being a mainter on a repository like this is a great opportunity to
learn maintainer skills and to do so in a low risk situation.
Solving merge conflicts, managing community members, and lowering friction
for developers are all important skills for working on open source
code repositories. This repository is merely a list, so the stakes
are low. There is no production service to break or be "down".
If you don't visit the GitHub notifications page often in the normal course
of your life, you might want
to set a reminder to double check notifications page so nothing gets missed.

#### Put it on your resume
#### How responsive do maintainers need to be?

While the stakes are low, the impact is high.
This repository is one of the most starred repositories on GitHub
under the 'geoscience' topic, Being a maintainer on this resume
is something that one can list on
their resume as evidence of contributing to the open source geoscience
community and evidence of their experience solving merge conflicts,
working with external contributors, etc.
Faster is better as it makes people who submit an issue or pull requests
feel more included when they get a fast response.
In practice, this repository has been managed in a very asynchronous manner
with pull requests often getting responses in 1-2 week range and sometimes unfortunately significantly longer. We should probably try to reduce this time to first response.

0 comments on commit 48076b7

Please sign in to comment.