Skip to content

Instantly share code, notes, and snippets.

@aviflax

aviflax/How the API Team Works.md Secret

Created January 20, 2013 04:00
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save aviflax/8c72e7a636bdb09ee555 to your computer and use it in GitHub Desktop.
Save aviflax/8c72e7a636bdb09ee555 to your computer and use it in GitHub Desktop.
Download ZIP
I worked with my team to develop this document as we formed a new team which had people joining gradually over time. We needed a way to get new people ramped up on the culture and process of the team quickly, and a way to have that culture and process be stable and referenceable but also adaptable.
Raw
How the API Team Works.md

This document “extends” the primary project documentation with content specific to the API team. All the content of the primary documentation remains relevant and in force. For example, the workflow section of the page Development Process specifies that we use the workflow known as git-flow; this provision remains in effect.

Continuous Improvement

  • The way the team works is meant to be a living process, one which is continuously improving and adapting to changing circumstances
  • Don’t ever hesitate to speak up if you have thoughts on how we can work better as a team!

Documentation

  • Documentation is critical
  • When in doubt, document
  • All documentation relevant to the entire platform, the entire project, or to more than one team, should be created in the primary project documentation (repo)
  • All documentation relevant only to the API team, such as this document, should be created in the API wiki
    • e.g. refactoring plans, internal process, etc.

Collaboration

  • The API team strives to work like an open source project
  • Written communication is preferred over verbal
  • Asynchronous commununication is preferred over synchronous
  • Email is discouraged. For asynchronous communication, tickets and pull requests are strongly preferred, as they keep the scope of conversations clear and limited. For large or amorphous topics, start a Basecamp discussion and prefix the subject with [API Team]
  • IM is discouraged. Team members are encouraged to hang out in the API Team chat room for informal ad-hoc synchronous collaboration, as long as it doesn’t interfere with their focus or productivity. No one is required to be in the chat room. If notable decisions are made or information is revealed in the chat room, is must be documented or disseminated via a different medium.
  • Decisions must be documented
  • Work should be visible and expose process. Work should have a URL. It should be possible to move backward from a piece of product or a system failure and understand how it came to be that way. Prefer git, documents, JIRA tickets, pull requests, Basecamp, and Campfire over URL-less mediums.
    • (Adapted from The github.com product development documentation.)

Campfire

  • When you want to get someone’s attention, use Campfire’s “mention” feature
    • Type @, a few characters of the person’s name, then press tab repeatedly until their full name appears. Then type your message and hit enter/return as per usual.
  • Try to ensure that the client you use to access Campfire is configured to display notifications if someone uses the “mention” feature to “mention” you
  • Try to remember to manage your Campfire presence; when you’re stepping away from your device which is logged into Campfire, click the leave link to leave the room temporarily, and rejoin the room once you return

Links to the Systems we Use

JIRA Tickets

  • As soon as you’ve started work on a ticket, make sure to click the button Start Progress
  • Once the work product for a ticket has been merged into develop, reassign the ticket to the release manager
    • The current release manager is Avi Flax
  • Once the work product for a ticket has been released and/or deployed, the release manager should click “Dev Complete” to set the ticket’s status to QA-WIP, and also change the assignee to unassigned

Work Assignments

  • All work is broken into discrete items and placed on the project’s current Kanban board in relative priority
    • these items are called “cards” in the Kanban context, and are represented by JIRA tickets
    • a card which is higher is more important than one which is lower
  • When a team member is ready for more work, he or she should:
    1. open the Rapid board
    2. if it isn’t already selected, select the “quick view” for unassigned cards
    3. choose one of the top 2 unassigned cards in the “To Do” column
    4. check whether the card is blocked. if it is, choose a different one.
    5. assign the card to himself/herself
    6. click “Start Progress”
    7. do the work

Git Workflow

  • We use the workflow “git-flow” as described by our development process
  • No one may commit or merge directly to develop — changes may only be added to develop via Pull Request (PR)
    • The sole exception is changes which are absolutely trivial and are to non-code files only — in that specific case only, commits may be made directly to develop

Code Review

  • All non-trivial changes to the repository must be reviewed by at least 2 team members
    • Any major changes should be reviewed by more than 2 team members
  • It’s the responsibility of the person who’s made the change to request review, to fully describe the goals of the change, and to note how many reviewers are needed
  • Reviewers must review the code with these goals in mind:
    • to fully understand the intent of the change, and to confirm that
    • to fully understand the changes
    • to work with the requestor to ensure that:
      • the change fulfills its intent
      • the changes are of superior quality
      • the test suite has been updated so as to thoroughly test the changes
        • and if the change is a bug fix, that a failing test has been created to catch the bug
      • all tests pass
      • the reviewer will be fully comfortable supporting, maintaining, and owning the code once the changes are merged

Pull Requests

  • All Pull Requests must include in the description:
    • A link to the JIRA ticket
    • Either **Ready** for final review, **Ready** for preliminary review, or **Not ready** for review
  • After posting a Pull Request (PR), add a link to the PR to the JIRA ticket
  • A Pull Request (PR) must have at least 2 unqualified :+1: or +1 comments before it can be merged into the develop branch
  • Any member of the team may merge a PR into develop except the team member who created the PR
    • For small or medium branches which contain low-risk changes, it’s recommended that the second reviewer to comment with a 👍 just go ahead and merge the PR after posting that comment
  • Pull Requests must be merged using the green “Merge” button in the PR page
    • i.e. they cannot be merged using a local git client
  • When you push more commits to an existing PR which has already undergone some review, and you need it to be re-reviewed, make sure to post a comment to the PR making that clear
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment