Skip to content

Workflow Guide

Jump to bottom
Brandon Ingli edited this page Apr 21, 2022 · 14 revisions

NOTE: This document is subject to periodic updates.

Project Tracking

Status Definitions

  • Idea: New issues go here automatically. They'll either be accepted and put in the queue or denied. Please do not start work on these Issues until they are accepted. Only Project Leads may accept Issues.
  • Accepted/To-Do: The queue (in no particular order) of accepted issues.
  • On Hold: Someone started working on it, but something else came up. This may be due to a dependency, waiting on information, or something more important came up. Please comment with a reason why the issue is being put on hold when you do so.
  • In Progress: Someone's working on it now.
  • Needs Review: Code is done, but a peer needs to review the work. New or Reopened PRs go here automatically.
  • Reviewed: The code passed peer review, but isn't merged into main yet. PRs with a passing review go here automatically.
  • Merged / To Be Released: The code has been merged into main, but not officially announced or released yet. Merged PRs go here automatically.
  • Released / Announced: These changes have been added to the appropriate changelog and are live on any instances of BADI we maintain.
  • Won't Do: These will not be worked. Only Project Leads may move Issues here. PRs closed with unmerged commits should be moved here.

Labels

Only Project Leads can add labels above and beyond what is set by the Issue and PR templates, with the exception of a Blocked label (see below).

Milestones

Only Project Leads should create and add Issues/PRs to milestones.

Issues

Any work requested to be done on the codebase must first be filed as an issue.

Where to File Issues

Please file issues to the correct repository. For example, issues regarding documentation on the website should be filed to that repo, not the interpreter repo.

If you have a question about where an issue should go, please ask. We can also transfer the issue to another repo if it's accidentally filed to the wrong one.

Dependencies Must Be Documented

If an Issue depends on another Issue being worked, indicate so in the description or a comment. Include a link to the other Issue. Then, apply a blocked label to the blocked Issue.

Assign Issues When Working

Assign an issue to yourself before you begin working it. If you see an accepted Issue assigned to someone else, reach out to them before grabbing it to work. Project Leads may assign issues to specific people to work.

When to Move Issues Between Statuses

  • Only Project Leads may move an Issue out of the Idea status or into the Won't Do status.
  • All contributors should move issues to In Progress, On Hold, and Needs Review as appropriate.
  • Reviewers should move the corresponding issue to Reviewed once the attached PR passes review, or to On Hold if the attached PR needs changes. This will be automated as soon as GitHub allows.
  • The PR Filer should move attached issues to Merged/To Be Released once the attached PR is merged.

PRs

PRs Required

All code to be included in the main branch must go through a Pull Request first. This applies to Project Leads as well.

Reviews Required

At least one person other than the pull request filer must review and approve the PR. The filer may request a specific person to review. Reviews become invalidated if another commit is pushed after the review is submitted.

Status Checks Required

Any requisite status checks, such as passing automated tests, are required to pass before a PR can be merged.

Pressing the Green Merge Button

The PR filer shall have the honor of pressing the big green Merge button when all checks and reviews have passed.

Git Conventions

Branch Names

When possible, start your branch name with the issue number if that issue is in the same repository as the code you're working on, e.g. #2-an-issue. Should the issue and code be in separate repositories, do not start with an issue number to avoid erroneous linking to issues.

Branch names should always be descriptive of what feature is being worked on.

Commit Messages

When possible, start your commit message with the issue number if that issue is in the same repository as the code you're working on, e.g. #2: Did a Thing. Should the issue and code be in separate repositories, do not start with an issue number to avoid erroneous linking to issues.

Commit messages should always be a short, descriptive summary of what was committed. If you need a longer explanation, use the body.

Deleting Branches

Do not immediately delete branches once a PR is merged. Project Leads will periodically audit the branches for those merged and deemed not necessary anymore.

Communication Guidelines

Use Threads for Related Conversation

When engaging in a conversation about one distinct topic / bug / idea, reply in a thread. This helps keep communication organized and contained.

Mention Sparingly

@everyone / @here / @role

Only use these mentions (if permissions allow) when it is imperative that everyone knows about something. This is fairly rare.

@user

Only mention a particular user when they are directly affected, or their opinion/knowledge is expressly requested in a conversation, especially when in a threaded conversation.

Mute Channels Selectively

You should not mute the entire server at once.

Channel Types OK to Mute

Log channels and miscellaneous discussion channels (e.g. #memes) are okay to mute at your discretion.

Channel Types Not OK to Mute

Development channels and overall announcement channels should never be muted.

Clone this wiki locally