Skip to content

Overhauling the participating docs #1611

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Overhauling the participating docs #1611

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 54 additions & 11 deletions docs/content/contributing/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,65 @@ weight: 4

Welcome, Gopher! We're really glad you're considering contributing to Athens. We'd like to briefly introduce you to our community before you get started.

We have some hard-and-fast rules in our community, like our [Code of Conduct](https://github.com/gomods/athens/blob/master/CODE_OF_CONDUCT.md), but instead of making rules pre-emptively, we try to keep in mind a shared philosophy to help us all make decisions and make new rules when we need to.
## Our philosophy

## Our Philosophy Document
We have three things (below) that we'd like you to keep in mind while you're contributing to the community. We won't always do all of these perfectly because, well, nobody's perfect!

The [philosophy section](/contributing/community/philosophy/) of these docs details our philosophy, and if you get involved with our project we encourage you to read it. If you're just browsing for now, here's a brief summary:
Our goal is to try our best.

- **Be Nice to Each Other** - people > code all the time, every time. We think that if we focus on our relationships with each other, we'll end up with better technology, better code, and a better community.
- **Make Development & Testing Easy** - Well, as easy as possible. This helps us reduce cognitive load so we can focus on Athens, not setting up our dev/test environment.
- **Focus on the Commmunity** - "If you want to go fast, go alone. If you want to go far, go together." We all try to follow this proverb. We try to get as many people involved as we can, we do (almost) everything 100% transparently, and we trust each other to do the right thing.
### Be nice to each other

## Where to Go from Here
We think that people are more important than code all the time, every time. We don't ignore code or settle for subpar technology, but we think that if we focus on our relationships with each other, we'll end up with both a better community and above-par technology anyway

We hope you like what you see, and we'd love for you to get involved.
### Make development and testing easy

If you're familiar with Git and GitHub basics, read [how to participate in the Athens community](./community/participating) to learn about how we organize ourselves and how to get started.
Well, as easy as possible. This helps us reduce cognitive load so we can focus on Athens, not setting up our dev/test environment.

If you're new to Git and GitHub, check out our [guide for new contributors to open source](./new), and then go on to that how to participate document I mentioned above.
### Focus on the community

Finally, if you are a new maintainer of the project, we have some documentation written for you at [./maintainers](./maintainers).
>If you want to go fast, go alone. If you want to go far, go together

We all try to follow this proverb. We try to get as many people involved as we can, we do (almost) everything 100% transparently, and we trust each other to do the right thing.

We have a [philosophy section](/contributing/community/philosophy/) of these docs details our philosophy. For now, the above three sections are fine. If you get more involved with our project, we encourage you to read it.

## Rules

Generally speaking, we don't make policies before we need them. We prefer looking at patterns and considering our philosophy before we come up with a rule. This goes for things like deciding on a new requirement for pull request reviews and more.

However, we have **one non-negotiable rule, our our [Code of Conduct](https://github.com/gomods/athens/blob/master/CODE_OF_CONDUCT.md)**.

>We have no requirements for joining our community, except that you click on that link and get familiar with our code of conduct

Unfortunately, I have to say this: _not knowing about or code of conduct is not an excuse for bad behavior. We enforce the code of conduct the same for everybody_.

If you see a violation of our code of conduct, there are instructions under [enforcement](https://github.com/gomods/athens/blob/master/CODE_OF_CONDUCT.md#enforcement) for what to do.

## Next steps

Now that all of that's out of the way, we hope you like what you see in Athens, and we'd love for you to get involved!

We welcome any contributor, regardless of who you are or what your experience/skill level is. We've tried to add a section below for all of the skill levels that we could.

### If you're familiar with Git and GitHub basics

Please read the [how to participate in the Athens community](./community/participating) document to learn about how we organize ourselves and how to get started.

### If you're new to Git and GitHub

If you're new to Git and GitHub, please check out our [guide for new contributors to open source](./new).

When you're done with that, please come back here, and check out the section I mentioned above!

### If the above sections don't apply to you

Looks like we didn't add enough sections! Come talk to one of us in our chat room. Here's how to join:

- First, get an invite to the [Slack](https://slack.com/) group [here](https://invite.slack.golangbridge.org/)
- Your invite should come almost right away
- Next, find the `#athens` channel
- You can ask a question in there if you're comfortable. You can also just introduce yourself!

### I'm a new maintainer of the project

We have some [documentation written just for you](./maintainers).
125 changes: 13 additions & 112 deletions docs/content/contributing/community/participating.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,126 +5,27 @@ weight: 1

---

Absolutely everyone is welcome to join our community at any time! We
are a friendly and inclusive group and we'd love to have you. We have three
roles in the Athens community:
Thanks for considering participating in the Athens community!

- Community member
- Contributor
- Maintainer
I want to start by saying:

Read on to find out more!
>Absolutely everyone is welcome to join our community at any time, regardless of who you are or your experience level

# Community Members
We are a friendly and inclusive group and we'd love to have you. We only ask that you follow the [code of conduct](https://github.com/gomods/athens/blob/master/CODE_OF_CONDUCT.md)

Community members are folks who decide they want to get involved with our
community. Absolutely anyone can do that whenever they want. If you want
to get involved, that doesn't mean you have to commit to being involved, but
we hope our community is welcoming and the work is interesting enough to
convince you to stay :)
## Ways to get involved

We'll provide all the support we can possibly provide to help you contribute
in any way you'd like. If you're considering joining us, here are some ideas
for how you can get involved:
You don't need to do anything fancy to contribute, and there are many ways beyond code that you can do so. Below is a list of some of the ways you can get involved. We know at least one person who has already gotten involved in each of these ways:

- Comment on an [issue](https://github.com/gomods/athens/issues) that you're
interested in
- Submit a [pull request](https://github.com/gomods/athens/pulls) (PR) to fix
an issue, or to improve something that doesn't have an issue
- Review a PR that you're interested in
- Join us at [office hours](/contributing/community/office-hours/)
(or more than one!)
- See [here](https://www.youtube.com/playlist?list=PLAk08AWjk5sekD-FRjU4VVe97nltUyZ4W) for recordings of all our past meetings
- Come chat with us in the [gophers slack](https://invite.slack.golangbridge.org/) in the `#athens` channel
- ... and anything else that's appropriate for you!

# Contributors

As you participate in the community more and more, you'll have the opportunity
to become a contributor. Here's what being a contributor means, and what you
should do to become one.

## What Being a Contributor Means

Contributors have read access to the Athens repository on Github. This means
that as a contributor, you're able to have issues assigned to you and you'll
be requested to review pull requests (PRs) via the
[Github pull request review system](https://help.github.com/articles/about-pull-request-reviews/).

We rely heavily on the Github PR review system, which means that if you review
a PR as a contributor, you can help decide when that PR is ready to be merged.
Don't worry that you _don't know enough_, the final approval and merge will be
by one or more maintainers.

## How to Become a Contributor

To become a contributor, the core maintainers of the project would like to see
you:

- Attend our development meetings regularly<sup>1</sup>
- Comment on issues with your experiences and opinions
- Add your comments and reviews on pull requests (anyone can do this as a
community member)
- Contribute PRs to fix issues
- Open issues as you find them

Contributors and maintainers will do their best to watch for community members
who may make good contributors. But don't be shy, if you feel that this is you,
please reach out to one or more of the contributors or maintainers.
We'll provide all the support we can possibly provide to help you contribute in any way you'd like. If you're considering joining us, here are some ideas for how you can get involved:

# Maintainers

After you become a contributor, you'll have the opportunity to become a
maintainer.
Here's what being a maintainer means and how to become one.

_Note: We sometimes refer to maintainers as "core maintainers," but they're
the same thing._

## What Being a Maintainer Means

As a maintainer, you'll be doing the same things as a contributor with a few
extras:

- Help organize our development meetings (i.e. help organize the agenda)
- Promote the project and build community (e.g. present on it where possible,
write about it, ...) when possible<sup>2</sup>
- Triage issues (e.g. adding labels, promoting discussions, finalizing
decisions)
- Organize and promote PR reviews (e.g. prompting community members,
contributors, and other maintainers to review)
- Help foster a safe and welcoming environment for all project participants.
This will include enforcing our code of conduct. We adhere to the [Contributor
Covenant](https://www.contributor-covenant.org), if you haven't read it yet you can do so [here](https://www.contributor-covenant.org/version/1/4/code-of-conduct) (english version).

## How to Become a Maintainer

To become a maintainer, we would like you to see you be an effective
contributor, and show that you can do some of the things maintainers do.
Maintainers will do their best to regularly discuss promoting contributors.
But don't be shy, if you feel that this is you, please reach out to one or
more of the maintainers.
- Comment on an [issue](https://github.com/gomods/athens/issues) that you're interested in, or have a question on
- Submit a [pull request](https://github.com/gomods/athens/pulls) (PR) to fix an issue
- You can also submit a PR to do something that isn't already an issue. We recommend that if you want to make a big change, you do talk to us first
- Review a PR that you're interested in
- Ask a question in a [GitHub discussion](https://github.com/gomods/athens/discussions)

# The End
If you don't see something in the list above that suits you, come chat with us - or introduce yourself! - in the [gophers slack](https://invite.slack.golangbridge.org/) in the `#athens` channel.

The above descriptions lay out roughly what each role is and how you can
move into each of them. Folks all have different strengths, live
in different places, and so on. We're a diverse group, and we want to keep it
that way!

So, everything in this document is a guideline, not a hard-and-fast rule.
If you are really good at something, or can't do something else, talk to
one of the maintainers and let us know what's up. We will accommodate
everyone the best we can.

---
<p><i>
<sup>1</sup> Athens development meetings are during the day in US Pacific Time.
We know that this time can be problematic for some folks due to work commitments,
different time zones, and so on. If you can't come to meetings, that's totally ok
and doesn't mean you can't become a contributor! Just let one of the maintainers
know about it, or leave a message in <code>#athens</code> in the <a href="https://invite.slack.golangbridge.org/">gophers slack</a>.
</i></p>
<p><i>
<sup>2</sup> Anyone and everyone is of course welcome to do this too!
</i></p>
97 changes: 97 additions & 0 deletions docs/content/contributing/roles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
title: "Roles in teh community"
date: 2020-05-06T13:58:58-07:00
weight: 4
LastModifierDisplayName: "Aaron"
LastModifierEmail: "[email protected]"
---

If you've read other parts of this site, you probably already know that **[absolutely everybody is welcome here](https://arschles.com/blog/absolutely-everybody-is-welcome/)**.

If you come join the community and make regular contributions, we will ask you if you would like to help lead the project.

We have two "roles" that we use to describe what that means.

## The contributor role

As you participate in the community more and more, you'll have the opportunity to become a contributor. Here's what being a contributor means, and what you should do to become one.

### What Being a Contributor Means

Contributors have read access to the Athens repository on Github. This means that as a contributor, you're able to have issues assigned to you and you'll be requested to review pull requests (PRs) via the [Github pull request review system](https://help.github.com/articles/about-pull-request-reviews/).

We rely heavily on the Github PR review system, which means that if you review a PR as a contributor, you can help decide when that PR is ready to be merged.

>If you are a contributor, the responsibility of reviewing and approving PRs will not fall completely on you. There are others to help!

### How to Become a Contributor

To become a contributor, the core maintainers of the project would like to see you:

- Attend our development meetings regularly<sup>1</sup>
- Comment on issues with your experiences and opinions
- Add your comments and reviews on pull requests (anyone can do this as a
community member)
- Contribute PRs to fix issues
- Open issues as you find them

Contributors and maintainers will do their best to watch for community members
who may make good contributors. But don't be shy, if you feel that this is you,
please reach out to one or more of the contributors or maintainers.

# Maintainers

After you become a contributor, you'll have the opportunity to become a
maintainer.
Here's what being a maintainer means and how to become one.

_Note: We sometimes refer to maintainers as "core maintainers," but they're
the same thing._

## What Being a Maintainer Means

As a maintainer, you'll be doing the same things as a contributor with a few
extras:

- Help organize our development meetings (i.e. help organize the agenda)
- Promote the project and build community (e.g. present on it where possible,
write about it, ...) when possible<sup>2</sup>
- Triage issues (e.g. adding labels, promoting discussions, finalizing
decisions)
- Organize and promote PR reviews (e.g. prompting community members,
contributors, and other maintainers to review)
- Help foster a safe and welcoming environment for all project participants.
This will include enforcing our code of conduct. We adhere to the [Contributor
Covenant](https://www.contributor-covenant.org), if you haven't read it yet you can do so [here](https://www.contributor-covenant.org/version/1/4/code-of-conduct) (english version).

## How to Become a Maintainer

To become a maintainer, we would like you to see you be an effective
contributor, and show that you can do some of the things maintainers do.
Maintainers will do their best to regularly discuss promoting contributors.
But don't be shy, if you feel that this is you, please reach out to one or
more of the maintainers.

# The End

The above descriptions lay out roughly what each role is and how you can
move into each of them. Folks all have different strengths, live
in different places, and so on. We're a diverse group, and we want to keep it
that way!

So, everything in this document is a guideline, not a hard-and-fast rule.
If you are really good at something, or can't do something else, talk to
one of the maintainers and let us know what's up. We will accommodate
everyone the best we can.

---
<p><i>
<sup>1</sup> Athens development meetings are during the day in US Pacific Time.
We know that this time can be problematic for some folks due to work commitments,
different time zones, and so on. If you can't come to meetings, that's totally ok
and doesn't mean you can't become a contributor! Just let one of the maintainers
know about it, or leave a message in <code>#athens</code> in the <a href="https://invite.slack.golangbridge.org/">gophers slack</a>.
</i></p>
<p><i>
<sup>2</sup> Anyone and everyone is of course welcome to do this too!
</i></p>