Participating in the Community

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:

• Community member
• Contributor
• Maintainer

Read on to find out more!

Community Members

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 :)

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:

• Comment on an issue that you’re interested in
• Submit a pull request (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 (or more than one!)
  • See here for recordings of all our past meetings
• Come chat with us in the gophers slack 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.

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¹
• 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. If you’re happy with your contributions but want more of a role in steering the project then read more on being a maintainer.

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.

¹ 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 #athens in the gophers slack.

² Anyone and everyone is of course welcome to do this too!

Our Philosophy

This document lays out generally how we want to work with each other. It’s hard to make a rule or set a guideline for each and every situation that might come up in our community. That’s basically predicting the future!

We do of course set some boundaries like the code of conduct, but we want to fall back to this document for guidance when we encounter a new situation or question that we need to address.

Guiding Principles

This is the TL;DR of the whole document! The Athens project has a few guiding principles:

• Be nice to each other
• Make development & testing easy
• Focus on the Community
• Ask Questions

In the rest of this document, we’re going to go into detail for each of these items.

Be Nice to Each Other

We firmly believe that a nice, welcoming and constructive community comes first, and code and technology second. If the folks in the community around this project aren’t nice to each other, it doesn’t matter how cool our technology is.

• Let’s try to make newcomers feel welcome
• Let’s put our debates in Github issues, and be civil and constructive in them
• Let’s be empathetic
• Let’s listen more than we talk
• We’re in different time zones, so let’s respect that
• Let’s encourage each other to learn new aspects of our project

Most importantly, let’s be inclusive. Not everyone will share your point of view, communication style, and many other things. Try to consider their point of view and treat them with respect.

Make Development & Testing Easy

Cognitive load is bad when you’re writing code, so let’s try to minimize it.

• Getting started should be a one-liner
• Let’s make the hard things easier
• Docs are good, let’s keep them up to date
• Let’s make it pleasant to work with our code

Focus on the Community

There’s an African proverb that goes like this:

If you want to go fast, go alone. If you want to go far, go together.

We want to apply that wisdom to our community.

• It’s easy and sometimes tempting to do everything yourself
• But if we want to keep the project growing, it’s hard to have just a few people doing everything
• Related: the bus factor
• So let’s focus on bringing new people into the community, and getting them started (see: Be Nice to Each Other, above)

Ask Questions

Questions are a great way for us to share ideas and make the project and community better.

• If you don’t know something, try not to be afraid to ask
• If you think your question is stupid, ask it anyway
• … And if you’re still uncomfortable asking in public, ask a maintainer in private
• If someone asks you a question, it’s ok to answer it later
• Put answers on paper where everyone can read them, if you can
• … And FAQs are great to have - let’s do them!
• Newcomers have the best perspectives, so listen well to their questions

Office Hours

Athens developers get together for an hour or so approximately every week on a video chat to learn and discuss a part of the codebase. The hour is relatively unstructured, but generally it starts out with a core maintainer (usually @arschles) going into the details of a part of the codebase. From there, we just go where the questions take us.

This is a great opportunity for new community members to get more involved with the project in a low-pressure setting. It’s also a great setting for existing community members to gain a deeper understanding into the codebase.

We meet at this zoom video chat URL: https://arschles.com/zoom

Absolutely everybody is welcome to attend these meetings. You’re free to suggest topics to talk about, share your perspective, and participate as little or much as you’d like.

You don’t have to be a contributor to attend.

Logistics

All office hours happen using the zoom software. Before you come to the meeting, please make sure you have installed the zoom client using this link: https://zoom.us/support/download.

If you’d like to attend an office hours, please join the #athens channel in the Gophers Slack Group. An announcement will be made on Tuesday mornings to remind folks before the office hours start. You can also follow @arschles and/or @gomods on Twitter to get these announcements.

Usually, office hours are at 2pm (14:00) US Pacific time on Tuesdays.

The Zoom Software

Also, if you are using a Mac, there is a vulnerability that can allow arbitrary websites to activate your camera without your permission. Please see here for more information.

If you haven’t updated your Zoom software since July 10, 2019, please do so to fix this issue.

Triaging Pull Requests

Hi, Gopher! We’re glad you’re interested in getting into PR triaging. This page details how to do that. Let’s get started!

TL;DR

We’re trying to all work together to make sure all of our pull requests (PRs) get reviewed and merged efficiently. So, we set up an easy way for anyone to “triage” pull requests on any Monday, Wednesday or Friday.

PR triaging means looking at older PRs and do either or both of these things, as appropriate:

• Prompting reviewers to come back and re-review
• Prompting submitters to come back and address reviews

Absolutely anyone can do triaging, and this is a great way to get involved with the community.

Sign up for triaging here.

Intro

The Athens community all works together to keep up to date on issues and pull requests. For issues, we take some time each week to review issues in the next milestone and others that folks are interested in.

We try to keep PR reviews moving a little bit faster and more efficiently, so we look at those 3 times a week.

PR reviews are asynchronous:

• A PR gets submitted
• You leave feedback in your review
• The submitter reads and addresses it (e.g. change code or respond to the comment) your feedback sometime later
• You come back and re-review sometime after that

I personally love the asynchronous workflow, but life happens - people forget, people get busy, go on vacation, etc… - as they should! We’re all human and we need breaks like that.

The problem is that PR reviews can get stalled. So, it’s important to make sure that a PR doesn’t sit idle for too long.

We’re getting a person to come check in three times a week to make sure that older PRs are still getting attention.

Triage Schedule

Since we don’t have a super huge volume of PRs, we’re looking for folks to do the following on a triage day:

• Look at PRs not updated in the last 3 days
• Add a comment to prompt reviewers and the submitter to come back to the PR:
  • If new commits have been added to the PR since 1 or more reviewer has done a review, please prompt those reviewers to come back and re-review
  • If there are still comments pending and the submitter hasn’t addressed them, please prompt the submitter to look at the new comments
• If you see a PR that hasn’t been updated in more than 10 days, write this in the PR comments and we’ll come figure out what’s going on (probably contact someone directly or close the PR): @gomods/maintainers this PR is really old!

If you need to prompt someone in your triage, do it by mentioning someone on GitHub like this: @arschles can you look at this again?. If you notice that someone has been @mentioned already, you can try pinging them on Slack. If you ping them, be nice and remember that they might be busy with other things though :)

How do I Sign Up?

Anyone, regardless of background, experience, familiarity with the project, time zone, or pretty much anything else. This is a wonderful way to get involved with the project. Triages generally take 15 minutes or less if you’ve done a few before (see the bottom of this section if you haven’t).

If you’d like to do triaging on a particular day, please add your name to the triaging spreadsheet.

If you haven’t done a triage before and would like to get started, please submit an issue.

If any of this doesn’t make sense, please contact us in the #athens channel in the Gophers Slack and we’ll clear it up and get you started.

Can this be Automated?

Probably, yes! But we don’t know if there are exact criteria on when PRs should be “prompted” and how a bot should do that. Maybe we’ll learn those criteria here.

Even still, it’s nice to have a human touch as a submitter and reviewer. It matches our philosophy very well.

Using Git

What is git?

Git is a free and open source distributed version control system. What does that really mean? It is a way to track changes to files on your computer. This is like keeping a detailed log of every time you change a file, what lines and characters were changed. So you could look at the log and see what changed, or undo those changes if you wanted or if you are working with others you can merge your changes together.

It’s a lot to take in, so don’t worry if you aren’t following yet.

If you want a more detailed walk through than we provide here, have a look at the Git Book.

Installing

Let’s start by getting git installed on you machine. You can check if it’s already installed by running git --version from the command line.

Follow your operating system specific instructions in Chapter 1.5 of the Git Book.

Basic concepts

Repository

This is a file structure on disk, like a database, it contains all files and the log of changes.

Staging

When you make changes inside a repository, they are untracked. You decide which changes to track, as you add changes they are added to the staging area. This let's you see all current changes before committing them.

Commit

After you are happy with the changes tracked in staging, you can commit them to the log we mentioned. You have a few options for writing a message that will be stored with the commit in the log, more on that later.

Branch

When you are in the repository the default out of the box is usually called `master`. This is the main branch of the repository (NOTE: if you are creating a new repository of your own, please change the default branch to `main`. `master` is an inappropriate and offensive), the main branch of the repository. Typically you will want to do your work on a new branch for each feature or bug. This allows you to see and work on different versions of the same code in one repository.

Checkout

To check out a branch, is to switch to view that branches version of the files in the repository.

Merge

When you want to incorporate another branch, `main` or someone else's feature for example, into your current branch you will merge the changes. This will apply the other changes on top of yours.

Remote

This is just a repository, that is accessible remotely. You can use the git command to push and pull changes to.

Push

Pushing to a remote will synchronize your locally committed changes to the remote.

Pull

Pulling from a remote will both fetch and merge the changes on the remote with the branch you have currently checked out.

Fetch

When you want to get some remote branch or changes, but not merge them yet, you can fetch them. Just ask the remote for the data and store it locally but not incorporate it into anything. You could then checkout the feature branch and run the code, or read over the changes.

Try it out

There is a great interactive tutorial, for free, available at Code Academy. Take some time to play with it and try out some of the commands.

Docs

Contributing To Docs

Contributing to docs is just as important, if not more important than, writing code. We use GoHugo to run this website. So if you’d like to improve it, here’s how you can run it locally:

1. Install the Hugo binary: https://github.com/gohugoio/hugo#choose-how-to-install
2. cd ./docs && hugo server

The Hugo server will run on http://localhost:1313 and it will automatically watch your files and update the website every time you make a change.

Alternatively you can run our custom docker image as outlined here

Github

Using GitHub

We use GitHub to host the remote copy of our repository and both track our issues and manage our pull requests. If you haven’t signed up before, take a minute to go do that now. We’ll be right here when you get back.

Issues

On GitHub we use the concept of an issue to record every change needed in our code base. This means ideas, bugs, features, support, even just discussions.

Never hesitate to open an issue if you have question about the code or think you may have found a bug. Sometimes people will find part of the documentation or instructions difficult to follow, let us know if this happens.

In particular for our project on GitHub, we have a template for Bug Reports and Feature Requests with one for Proposals .. proposed. When you click on ‘New Issue’ you will be given a choice of which template to start with, if they do not seem to fit your need there is an option to ‘Open a regular issue’ - which is blank.

Forks

In order to keep things a bit tidy in our main repository, we all do work on what is called a fork before creating a pull request. A fork is essentially a copy of a repository that is owned by your GitHub account. You can create as many branches as you like there and don’t be shy with creating commits. We will squash them all into one before we merge, more on that below.

But first take a minute to read this awesome post on creating and maintaining a fork of the project. It even goes into adding other collaborators forks as remotes which you will find useful as you start working more and more with other contributors.

Pull requests

Brian Ketelsen created an awesome video on making your first open source pull request, for an overview of the process go watch that now. There’s also a great video series on contributing to an Open Source project by Kent C. Dodds.

When we receive a new pull request, it may take time for a maintainer or other contributor to get to it, but when we do a few things will happen.

You can expect at least a few comments, don’t let them discourage you though. We are all trying to help one another write the best code and documentation possible, all criticism should be considered constructive.

If you feel like it is not, please do not hesitate to reach out to one of the maintainers. We take our code of conduct very seriously.

Most likely one or more contributors and maintainers will leave a review on your pull request. You can discuss the changes requested in the pull request itself, or if you need help with something in particular you can reach out to us in the #athens channel on Gophers Slack.

After all requested changes are resolved a maintainer will give it a final look and as long as our continuous integration passed they will merge it with the main branch.

Project process

Let’s just go over a quick general guideline on contributing to Athens.

Find an issue

When you see an issue you would like to work on, if no one else has expressed interest please comment on the issue with something like:

• I will take this
• I would like to work on this

This let’s other contributors know someone is working on it, we all know free time is hard to get and don’t want anyone wasting theirs.

If you don’t see an issue for your bug or feature, please open one to discuss with the community. Some things may not be in the best interest of the project, or may have already been discussed.

If your issue is something very small, like a typo or broken link, you may skip straight the pull request.

Open a pull request

After you have created a branch on your fork, and made the changes. Please make sure all tests still pass, see DEVELOPMENT.md for details. Then after you push all changes up to your fork, head over to Athens to open a pull request. Usually, right after you have pushed a new branch and you visit the original repository, GitHub will prompt you to open a new pull request. Otherwise you can do so from the Pull Requests tab on the repository.

How To Contribute

Development Guide for Athens

The proxy is written in idiomatic Go and uses standard tools. If you know Go, you’ll be able to read the code and run the server.

Athens uses Go Modules for dependency management. You will need Go v1.12+ to get started on Athens.

See our Contributing Guide for tips on how to submit a pull request when you are ready.

Go version

Athens is developed on Go v1.12+.

To point Athens to a different version of Go set the following environment variable

GO_BINARY_PATH=go1.12.X
# or whichever binary you want to use with athens

Run the Proxy

If you’re inside GOPATH, make sure GO111MODULE=on, if you’re outside GOPATH, then Go Modules are on by default. The main package is inside cmd/proxy and is run like any go project as follows:

cd cmd/proxy
go build
./proxy

After the server starts, you’ll see some console output like:

Starting application at 127.0.0.1:3000

Dependencies

Services that Athens Needs

Athens relies on several services (i.e. databases, etc…) to function properly. We use Docker images to configure and run those services. However, Athens does not require any storage dependencies by default. The default storage is in memory, you can opt-in to using the fs which would also require no dependencies. But if you’d like to test out Athens against a real storage backend (such as MongoDB, Minio, S3 etc), continue reading this section:

If you’re not familiar with Docker, that’s ok. We’ve tried to make it easy to get up and running:

1. Download and install docker-compose (docker-compose is a tool for easily starting and stopping lots of services at once)
2. Run make dev from the root of this repository

That’s it! After the make dev command is done, everything will be up and running and you can move on to the next step.

If you want to stop everything at any time, run make down.

Note that make dev only runs the minimum amount of dependencies needed for things to work. If you’d like to run all the possible dependencies run make alldeps or directly the services available in the docker-compose.yml file. Keep in mind, though, that make alldeps does not start up Athens or Oympus, but only their dependencies.

Run unit tests

In order to run unit tests, services they depend on must be running first:

make alldeps

then you can run the unit tests:

make test-unit

Run the docs

To get started with developing the docs we provide a docker image, which runs Hugo to render the docs. Using the docker image, we mount the /docs directory into the container. To get it up and running, from the project root run:

make docs
docker run -it --rm \
        --name hugo-server \
        -p 1313:1313 \
        -v ${PWD}/docs:/src:cached \
        gomods/hugo

Then open http://localhost:1313.

Linting

In our CI/CD pass, we use govet, so feel free to run it locally beforehand:

go vet ./...