Dev Experience Processes

Planning and tracking work

Planned work

We use the DevX Planning document to asynchronously discuss our quarterly roadmap. Our Strategy page is updated monthly to reflect our team’s plans.

Unplanned work

We aim to allow teammates the flexibility to work on incoming requests, tackle proactive improvements, and invest in long-term efforts on our roadmap, so as a rule of thumb:

  • We aim to spend 20% to 30% (~2-3 days every 2 weeks) of our time on making proactive impact, i.e. working on things that are aligned with the team’s mission, but aren’t on our roadmap.
  • If over 50% (~5 days every 2 weeks) of our time is spent outside of planned work (i.e support requests), we opt to discuss the scope and priority of the work with the team first.

Tracking

As of , we use Github projects to keep track of our work.

Product and Engineering roadmap project

Our quarterly roadmap items are defined in tracking issues on the Product and Engineering roadmap. These tracking issues describe the problem space, requirements, proposed solution, key results, and measures of success; provide links to relevant RFCs, discussions, arifacts, and decisions; and collate the smaller issues that contribute to the execution of our roadmap. In this way, they reflect a high-level view of our progress on a given roadmap item and provide necessary context. These issues have the team/devx, roadmap, and tracking labels.

Dev Experience project

For a lower level view of our day-to-day progress, we use the Dev Experience Github project. This board automatically imports issues with the dx or team/devx labels.

Google Drive

We collect meeting notes and planning artifacts in a shared Google Drive folder.

Support

Requesting support

If you have a question that relates to our areas of ownership, the #dev-experience channel is the best way to reach us. Tag the @dev-experience-support handle if something is urgent (think of this as pulling the fire alarm) and requires our immediate attention. Our on-call teammate will jump in.

Raising an issue

If you think Dev Experience is the right team to address a bug or other request, please create an issue. The issue should include:

  • A short description of the ask
  • A more detailed explanation of the background, context, and problem that needs solving
  • Any guidance related to the impact of this issue
  • Any extra information that will help us solve or prioritize the issue
  • The label team/devx

Providing support

This section documents tips for teammates on support, which is handled via our support rotation. General tips:

  1. We are not responsible for every issue in CI - see build pipeline support and CI support responsibilities.
  2. git rebase is very easy for teammates unfamiliar with git to do incorrect - if a branch update is required, err towards recommending a git merge (e.g. git pull origin main).
  3. Make sure to update devx-scratch for any notable support efforts.
  4. Be wary of issues achieving joke/meme status: it often means that it is actually quite a disruptive issue, and warrants a closer look.
  5. Be liberal in asking for a video or screen recording to demonstrate DX issues: this can help us understand and emphathise with DX pains.

Build pipeline support

Build pipeline support pertains to our continuous integration. The goal of this process is to identify the right person to drive a fix on an issue, rather than actively fixing every issue that arises.

The on-call support teammate should monitor the pipeline through channels like #buildkite-main for flakes and notifications from buildchecker. If there are any issues, ensure issues are followed up on:

  1. Infer the owner based on the contents of the issue *e.g. through product names, git history, and/or other context) and reach out for assistance:
    1. If a team can be inferred, ping the @$TEAM-support handle in Slack for assistance, escalating to @$TEAM if no support handle or teammate is available.
    2. If no team is easily inferred, ping the most recent author via git blame where relevant for assistance.
  2. Guide the teammate towards a resolution for the issue by following our broken builds process (also see Continuous integration: Flakes).
CI support responsibilities

The DevX team is not responsible for all the tools and tests that run in Sourcegraph’s CI infrastructure.

If a tool or test is behaving in an unstable manner, the team using the tool or test (see build pipeline support for how we infer ownership) has the responsibility of leading an investigation into what might be causing said instability, with the assistance of the DevX team if helpful.

The team leading the investigation should either fix the issue directly, or if the issue requires changes in the DevX team’s ownership/responsibility areas (e.g. increasing resource limits for build agents, or making significant changes to the pipeline generator), request the desired changes through an issue tagged team/devx.

For a higher-level understanding of our responsibilities, see our guiding principles.

Team roles

Support rotation

We use OpsGenie to manage a support rotation that changes weekly. The person on-call will be pinged when someone tags @dev-experience-support in Slack. That person is expected to prioritize responding to the support request, but anyone who sees a request can and should jump in.

Work leads

For each major body of work, we assign an engineer to be a work lead. Work leads are responsible for working with the PM/EM to articulate the problem space, requirements, proposed solution, key results, and measures of success. They also scope a delivery plan and create issues to be tracked in the tracking issue. The work lead helps answer questions about priority order, scope change, etc., and provides updates at team syncs. They are not solely responsible for executing on the work, which is a team effort.

The work lead should:

  • Work with the PM/EM to create the roadmap tracking issue using the tracking issue bot.
    • Articulate the problem space, requirements, proposed solution, key results, and measures of success.
    • Scope the work to a manageable size for one team to deliver in one quarter.
    • Identify any applicable “Non-Functional Requirements”, such as testing, monitoring, and documentation.
    • Identify stakeholders to consult and/or dependencies on other work.
  • Create a delivery plan with issues to be tracked in the roadmap issue.
  • Maintain an understanding of the progress of the work.
    • Have a clear picture of what’s being executed, what’s coming up, and overall timelines.
    • Ensure required tasks are delegated.
    • Continually evaluate whether we are working towards our key results.
    • Work with EM/PM if any adjustments are needed.
    • Create follow-up issues for any known or outstanding bugs.

Team meetings and communication

We inherit Sourcegraph’s meeting principles and asynchronous communication guidelines with some modifications that help us run effective meetings:

  • Meeting leaders rotate weekly, and the leader should prepare the agenda at least 24 hours ahead of time.
  • All teammates should add items to the agenda before the meeting begins.
  • Any action items that come out of meetings should be considered a high priority.

Team sync

We connect weekly to discuss any topics that are best addressed in person. Our notes are available here.

Team retrospective

We connect bi-weekly to celebrate wins from the past two weeks, give cheers to our teammates, and reflect on what we’ve liked, not liked, and learned for going forward. The focus of the agenda for this meeting is team health, as opposed to day-to-day work.

Coffee break

Every week we hold an informal, totally optional coffee break to connect socially and hang out together as humans.

sg hack hour

There is a weekly sg hack hour that Thorsten Ball and the DevX team co-host weekly Fridays from to for anyone interested in making contributions to the Sourcegraph developer tool.

When the hack hour starts, a meeting link will be posted in #dev-experience.

To learn more about contributing to sg, check out the contribution guide!

Slack

Teammates communicate in #dev-experience, #dev-experience-internal, and #dev-experience-private, and post daily updates Geekbot in #dev-experience-updates.

Housekeeping

Weekly reminders

At the start of each week, the PM posts a reminder in #dev-experience-internal indicating who is on support and who is leading meetings.

Updating the Dev Experience project board

All engineers update the Dev Experience project board in advance of the weekly sync.

The status field for each issue in the project board roughly represents the following:

  • Unplanned: No concrete plans to tackle yet
  • Next iteration: Something to consider for next iteration
  • Planned: On somebody’s immediate plans (i.e. will be tackled roughly within this iteration)
  • In progress: Actively being worked on
  • Blocked: No progress can be made due to a dependency
  • External: DX-related work being handled by other teams
  • Done: That’s a wrap!

Updating the Product and Engineering roadmap

The PM and work leads own the roadmap issues. They solicit input from the team to make sure the problem space is thorough, measures of success are ambitious-but-reasonable, and technical details are correct.

Updating our Strategy page

The PM updates this page at the start of each month.

Newsletter

The DevX team is responsible for a monthly (ish) newsletter to highlight developer experience updates (not just those lead by the team). Learn more about it and see previous issues in the newsletter archive.

To prepare a new issue of the newsletter, create a PR for the latest newsletter issue here following the conventions in the previous newsletters. Some tips:

  • You can refer to dx-announce issues and PRs for content ideas!
    • Adding a closed:>YYYY-MM-DD will filter the list down to just things that have been closed since the last newsletter issue.
  • To include images, either follow the official guide or upload images to a GitHub issue - this will provide a shareable link.

Once the newsletter is ready and reviewed, merge the PR. Then copy and paste the rendered newsletter from the handbook (you can set this up locally with yarn dev) into a draft newsletter. You will need to remove the background color from the pasted content, but the formatting should otherwise just work.

Verify the output looks good, and email it to engineering-team@sourcegraph.com.

devx-scratch

We maintain a repository with experiments and notes from the DevX team, sourcegraph/devx-scratch, in an effort to improve knowledge-sharing and log our explorations and trends. We encourage you to log anything you want in this repository, particularly insights from pairing sessions and so on!

Of particular note is the support log (2022 support log), which should be update with any notable efforts during support rotations.