👋🏽 Welcome!

This is an experimental project to start gathering metrics about github organizations and repositories.

The goal is to get an idea of various "open source health" style metrics, such as:

  • which repositories are the most active?
  • who is contributing to them?
  • how long does it take to get reviews?

Ultimately, I'd like to use this data to help projects and contributors be more successful. For example, it'd be nice to know if someone has stopped opening PRs in the last month or two -- maybe there is something blocking them that can be fixed?

Want to help?

Great! This is a fun project to hack on because it's relatively simple. It's a good way to get acquainted with async Rust and Rust in general. I'm eager to grow a set of maintainers who can help the project grow and be useful, so if you think it sounds appealing, get in touch with nikomatsakis on the github-metrics zulip instance below.

Chat

We chat on the github-metrics zulip.

Generating a report

Optopodi is geared to generate reports. These are CSV files that summarize important information about your repository or repositories. To create a report you need to take the following steps:

  • Make a directory $DIR for the report. We recommend a name like data/2021-06-26.
  • Create a report.toml file in that directory. You can start with the template and customize it.
  • Configure a github token. This is loaded from one of two sources:
    • The GITHUB_TOKEN environment variable, if present.
    • Otherwise, from the github.oauth-token setting in ~/.gitconfig.
  • Optionally, create a crate-information.json file in $DIR.
    • This defines notable crates from the ecosystem that you wish to analyze.
    • If you don't have such a file, it will be generated for you. However, if the file is present, Optopodi will make use of the existing crate-information.json for reproducibility.
    • You can generate this file using the top-crates crate from the Rust playground if you wish to produce it manually.
  • Run cargo run -- report $DIR. This will populate the following subdirectories:
    • $DIR/graphql -- saved results of graphql queries. These can be "replayed" later to avoid hitting the network. This makes things faster and avoids generating tons of github API calls when debugging (which can easily exceed your quota).
    • $DIR/inputs -- intermediate CSV files containing data extracted from the graphql queries.
    • $DIR/outputs -- contains the CSV files you are meant to look at.
    • $DIR/crate-information.json will be generated if absent. This defines notable crates from the ecosystem that you wish to analyze.
  • You can run with the --replay-graphql setting to re-use saved graphql queries: cargo run -- --replay-graphql report $DIR
    • This is most useful when debugging or tweaking the code.

Contributing

Want to help? Great! This is a fun project to hack on because it's relatively simple. It's a good way to get acquainted with async Rust and Rust in general. You'll find lots of project ideas on the issues page.

Code of conduct

We follow the Rust code of conduct. Please report any concerns to a Lead.

Optopodi Collaboration Guidelines

Adopted from the Mentored Sprints discord server and The Recurse Social Rules these guidelines extend the Rust CoC in ways that are actionable and clear examples to follow for the Optopodi team.

Examples of behaviors that contribute to creating a positive environment:

  • Being friendly and patient
  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints and experiences
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

  • The use of sexualised or violent language or imagery
  • Unwelcome sexual attention or advances
  • Trolling, insulting/derogatory comments, and personal or political attacks
  • Public or private harassment. If someone asks you to stop, then stop.
  • Publishing others' private information, such as a physical or electronic address, without explicit permission
  • Advocating for, or encouraging, any of the above behaviour
  • Other conduct which could reasonably be considered inappropriate in a professional setting

The following are examples of good choices during collaboration with your team and choices to avoid. The Recurse Center did such an excellent job creating these examples that additional explanation is not needed.

These guidelines aren’t for punishing people.

Consider these guidelines to be lightweight. You should not be afraid of breaking one. These are things that everyone does, and breaking one doesn’t make you a bad person. If someone says, "hey, you just feigned surprise," or "that’s subtly sexist," don’t worry. Just apologize, reflect for a second, and move on.

Inclusive Language https://heyguys.cc/

Do use these terms: everyone, everybody, all, you all, y'all, folks, friends, people.

⛔️ Do not use "guys"

No well-actually’s

Alice: I just installed Linux on my computer!

Bob: It’s actually called GNU/Linux.

No feigning surprise

Dan: What’s the command line?

Carol: Wait, you’ve never used the command line?

No backseat driving

Bob: What’s the name of the string copy function?

Alice: Strncpy.

Eve: (injecting into an existing conversation) You should use strlcpy. It’s safer.

No subtle -isms

Carol: Windows is hard to use.

Bob: No way. Windows is so easy to use that even my mom can use it.

And finally, not every comment requires a response.

Chat

We chat on the github-metrics Zulip instance, found at https://github-metrics.zulipchat.com/.

Review policies

  • Anyone is welcome to leave a review.
  • We use bors, so don't merge by hand. If you are a reviewer, type bors r+ instead.
  • Only r+ code that you are familiar with.
  • Style nits and other minor concerns are welcome, but please be courteous. Labeling things as "nit" or including a comment that makes clear that these are minor points can be helpful.

Committers

Committer access is recognition of "significant contribution". Significant contribution represents several hours of work over multiple days:

  • Implementing a moderate feature
  • Non-trivial refactorings
  • Issue triage and general participation
  • Reviewing the code of others

Committers are expected to go "above and beyond" with respect to the Code of Conduct.

Committers have write access to the repository and r+ rights on bors.

Leads

Leads of the project have final decision in case of controversy. They also make membership decisions, such as who to add or remove from the committers group.

Leads are selected from committers based on a history of major contribution and committment.