Create:Remote Development Group

Overview

The group is part of Create Stage in the Dev Sub-department. We focus on two categories: Workspace and the Web IDE.

👌 Group OKRs

If you’re interested in the group’s Objectives and Key Results (OKRs), you can find them on GitLab.

🤴 Group Principles

Create:Remote Development Principles: What Are the Create:Remote Development Group Principles?

🚀 Team Members

The following people are permanent members of the Remote Development Engineering Group:

Engineering Manager & Engineers

Name	Role
Adebayo Adesanya	Engineering Manager
Chad Woolley	Staff Backend Engineer, Create:Remote Development
Cindy Halim	Fullstack Engineer, Create:Remote Development
Daniyal Arshad	Backend Engineer
Enrique Alcántara	Staff Frontend Engineer, Create:Remote Development
Joseph Fletcher	Associate Frontend Engineer
Paul Slaughter	Staff Fullstack Engineer, Create:Remote Development
Safwan Ahmed	Backend Engineer, Create:Remote Development
Vishal Tak	Staff Backend Engineer, Create:Remote Development
Zhaochen Li	Backend Engineer, Create:Remote Development

Product, Design, Technical Writing, Security & Quality

Name	Role
Jay McCure	Senior Software Engineer in Test, Dev:Create
Michelle Chen	Senior Product Manager, Create:Remote Development

☕ Category DRIs

Category	DRI
Workspaces	Vishal Tak
Web IDE	Paul Slaughter

🎓 New Hires

As the Remote Development team and tech stack continue to mature, it’s essential to have a team-specific onboarding process for new hires. This checklist is designed to guide new team members through the key areas and processes specific to our team, starting two weeks after company onboarding. It covers our mission, essential tools, and workflows related to the Web IDE and Workspaces. Existing team members are encouraged to review the checklist regularly and contribute any missing or updated information to ensure it remains accurate and useful for newcomers. You can find the template https://gitlab.com/gitlab-com/create-stage/remote-development/-/blob/main/.gitlab/issue_templates/remote-development-onboarding.md.

☎️ How to reach us

Depending on the context here are the most appropriate ways to reach out to the Remote Development Group:

• Slack Channel: #g_create_remote_development
• Slack Groups: @create-remote-development-team (entire team) and @create-remote-development-engs (just engineers)

🗣️ Capturing Customer Engagements

To improve our understanding and traceability of customer needs and to ensure followups action items are systematically done, we want to capture customer engagement notes in a SSoT. Please use the confidential issues below to capture all customer engagements for the two feature categories:

• Web IDE Customer Engagements
• Workspaces Customer Engagements

These epics are meant for internal team members only. If you are a user wanting to provide feedback, see Capturing User Feedback.

🗣️ Capturing User Feedback

We highly value user feedback! Please use the epics below to capture feedback and insights for the two feature categories:

• Web IDE User Feedback & Insights
• Workspaces User Feedback & Insights

For non-team members, feel free to create issues in these epics if you have general feedback or suggestions. If you have feedback related to existing or ongoing features, please drop a comment in the appropriate epic or issue.

Group Metrics Dashboards

Create::Remote Development Group Metrics Tableau Workbook

📆 Group Meetings

❗️Important: For every meeting, the Remote Development group’s meeting document should be used apart from High Level Planning which has a document of it’s own, and filled with the meeting notes, as well as references to any other sync meeting agendas/notes/recordings which have recently occurred. This will make it easier for people to find any meeting notes.

Please note that sync meeting schedules are flexible and can be moved to accomodate required participants. For up to date schedule of all team meetings, please consult the Group’s Calendar.

The table below briefly outlines the objectives and key details of regular team meetings:

📦 Group Processes

🖖 Weekly EM Updates

Each week the group EM provides a Weekly Status update issue which aims to capture the most important items for the team to be aware of. These can be found here.

😷 Issue Workflow Hygiene

In the Create:Remote Development group we leverage an automatic issue hygiene system via the triage bot. This helps to ensure issues and label hygiene are respected, currently, our rules are:

🌉 Architecture Plans vs. Iteration Plans

We use the terms Architecture Plan and Iteration Plan when we think of outcomes to broad high-level issues. An investigative spike should result in an Architecture Plan and an Iteration Plan.

• Architecture Plan: A high-level vision of a technical approach that is shown to solve user problems. This plan includes a formulation of specific quality attributes that are important for this use cases (such as performance, usability, or security). It also includes an outline of technical approaches that will satisfy these quality attributes in addition to the functional requirement. A spike effort should be created to verify and explore the technical approach for an architecture plan. The spike could result in new architectural concerns, resulting in an iteration of the plan.
• Iteration Plan: A plan for how we’ll iteratively implement an Architecture Plan or another objective. This can be composed of low-level technical steps, or medium-level slices of use cases. The iteration plan should result in a set of issues (and possible epics) with clearly defined scope and weights.

Sometimes it takes a time to develop a well fleshed-out iteration plan. In these cases, a “Formulate Iteration Plan” weighted issue can be used.

📝 Issue Guidelines

These guidelines apply to all issues we use for planning and scheduling work within our group. Our Engineers can define specific implementation issues when needed, but the overall goal for our issues are as follows:

• Treat the wider community as the primary audience (see relevant summary for rationale).
• Provide a meaningful title that describes a deliverable result.
  • ✅ Add a cancel button to the edit workspace form page
  • ✅ Automatically save Devfile changes after 2 seconds of inactivity
  • ❌ Make WebIDE better
• Provide a meaningful description that clearly explains the goal of the issue, and provide some technical details if necessary.
• Should there be critical implementation steps or other useful ways to create small tasks as part of the issue, please use a checklist as part of the issue descriptions.
• The issue should have a weight assigned.

It’s okay to create specific engineering-driven implementation issues for more complex features. These would be called Child Issues and they should always link back to their parent. If one issue would spawn many child issues, consider creating an Epic.

🤖 Planning Process

The Remote Development group has decided to use an alternate planning process for the following reasons:

1. Workspace is a large, greenfield category, with many engineering, infrastructure, and technical concerns and unknowns which will continue to evolve and change as the category matures.
2. The Workspace category is also currently receiving much attention as part of GitLab’s competitive strategy, and thus has greater internal and external expectations for accurate estimates of feature delivery and timelines.
3. In order to meet this need for more accurate and realistic planning and delivery estimates, the Workspace category team has decided to modify parts of the Plan and Build & Test phases of the GitLab Product Development Flow to a more lightweight velocity-based estimation and planning process inspired by the widely-used and popular XP and Scrum methodologies. The goal is to provide accurate delivery estimates based on “Yesterday’s Weather” historical velocity analysis.
4. To better support the use of these methodologies, the Remote Development group has committed to dogfooding the Iterations feature, and following the documented process for running agile iterations where possible.
5. However, due to existing limitations of the Iterations and Boards features in fully supporting these methodologies, we will also experiment with new and alternate tools and processes, with the goal of informing and potentially contributing back to improve GitLab’s support for them. More details will be shared as this effort evolves.

Even though the Web IDE category does not have all these constraints (e.g. it is based on VS Code and is not greenfield code, and has fewer unknowns), the Web IDE category will follow a similar process in order reduce the cognitive overhead of the entire group.

Planning Process Overview

The Remote Development group has modified parts of the Plan and Build & Test phases of the GitLab Product Development Flow to a more lightweight velocity-based estimation and planning process inspired by the widely-used and popular XP and Scrum methodologies.

The crux of these changes is focused around the following process phases:

1. “High Level Validation and Planning”. This is analogous to the Validation Track in the GitLab Product Flow, because it needs to achieve the same Validation Goals & Outcomes before we can start refining and prioritizing issues.
2. The “Pre-Iteration Planning Meeting”, or “Pre-IPM”. This is analogous to “backlog refinement” in the standard GitLab product development flow. The goal of the Pre-IPM is to ensure that all issues which are to be prioritized in the upcoming iteration(s) are ready for the wider team to briefly discuss and estimate in the next IPM.
3. The “Iteration Planning Meeting”, or “IPM”. This is analogous to the “Weekly Cycle” in XP or “Sprint Planning” in Scrum.

These components allow us to provide realistic velocity-based estimates based on “Yesterday’s Weather” historical velocity analysis.

IMPORTANT: note that these process changes do not represent a full adoption of XP or Scrum methodologies. Instead, they are a minimal and lightweight process “inspired” by XP and Scrum. The primary goal is to allow the team to provide realistic planning and delivery estimates to leadership based on accurate velocity measurements. The Pre-IPM and IPM processes are the minimal components which allow us to meet that goal.

Custom workflow labels

To facilitate the Remote Development group’s specific planning process, we make use of custom workflow scoped labels under ~workspaces-workflow:: or ~webide-workflow::. These custom workflow labels are necessary to work around current limitations of GitLab iterations and boards in implementing this process.

The Web IDE category uses the separate set of ~webide-workflow:: scoped labels, because this makes management of boards and workflows easier, especially in the case of issues which may have both categories’ labels applied.

GitLab Velocity Board Chrome Extension

To facilitate this process, especially around calculating emergent iterations based on velocity, we will use the GitLab Velocity Board Chrome Extension.

See this video for an overview of the extension, and also for an explanation of this general process, and why we need to use an extension to support it rather than the current standard GitLab Iteration and Board features.

This extension is in support of a GitLab OKR for Create. We plan to continue iterating in this area, with the goal of eventually having GitLab directly support this workflow.

Wider Board Columns

The default width of lists on boards can make the board harder to use, since you see fewer items and have to scroll more.

There is an open issue to address this. In the meantime, though, you can use the following javascript bookmarklet suggested in this comment on the issue, which will make the lists take up the full board width. Just make a bookmark named “Wider board lists” with this as the link:

javascript:(function(){var el=document.getElementsByClassName('boards-list');for(i=0;i<el.length;++i){el[i].style.padding=0;el[i].style.display='table';}el=document.getElementsByClassName('board');for(i=0;i<el.length;++i){el[i].style.padding=0;el[i].style.border='0';el[i].style.display='table-cell';}el=document.getElementsByClassName('board-inner');for(i=0;i<el.length;++i){el[i].style.padding=0;el[i].style.border='0';}})();

Iteration Planning Report

TODO: We need to create a Web IDE version of this report and link it in the category slack channel - there is an issue for this.

In addition to the Velocity Board chrome extension, there is a Workspace Iteration Planning Report and Web IDE Iteration Planning Report which are automatically published every 6 hours.

This report shows the same auto-calculated iteration/velocity data, and uses the same logic as the Velocity Board Chrome Extension, but you don’t have to install the extension to see it.

The pipeline to generate it can also be run directly from CI.

Process Phases

NOTE: All issues in this process must be assigned the ~Category:Workspace or ~Category:Web IDE label, even if they are also assigned another category label. Otherwise the board and velocity calculation tools will not work properly.

graph TD;
  S[issue created] -->|"New issue is added to an epic, and '(workspaces|webide)-workflow::unprioritized' label is applied"| V[High Level Validation and Planning]
  V -->|"'Next 1-3 Releases' milestone is applied to higher-priority issues"| R[Pre-IPM - Async Refinement]
  R -->|"Unprioritized issues with 'Next 1-3 Releases' milestone are assigned for refinement"| P[Pre-IPM - Sync prioritization]
  P -->|"Refined issues are prioritized into '(workspaces|webide)-workflow::prioritized'"| I[IPM]
  I -->|"'(workspaces|webide)-workflow::prioritized' issues are discussed and estimated by the entire team"| N[Next]
  N -->|"Issue is assigned to a specific release based on its calculated iteration"| E[Development proceeds for issue]

1. High Level Validation and Planning

Process:

TL;DR: Assign the Next 1-3 releases milestone to all issues that should be refined and prioritized in the next Pre-IPM meeting(s).

1. All higher-priority issues should be contained in the category epic or one of its sub-epics
2. They should all have the ~(workspaces|webide)-workflow::unprioritized label assigned.
3. All higher-priority issues should be assigned to the Next 1-3 releases milestone.
4. Issues which are not a priority to finish within the %"Next 1-3 releases" may have the %"Next 4-7 releases" or %"Next 7-13 releases" release applied, or alternately, they can be assigned to %Backlog or %Awaiting Further Demand.
5. Issues in ~(workspaces|webide)-workflow::unprioritized MUST NOT be left without a release applied. This should be enforced by automation. Use this issue search to identify Workspace issues which are missing a milestone

Explanation:

This process identifies and validates higher-priority issues to be worked on in the upcoming releases. It is analogous to the Validation Track in the GitLab Product Flow, and should consist of many of the same steps and processes.

In addition to validating features, this process can also result in Engineering identifying high-priority issue which are necessary to address Technical Debt or “Friction”.

There may be concerns about over-committing too many issues to the %"Next 1-3 releases" release. However:

1. If we are being healthy and diligent about following the Pre-IPM process every week as defined, we should be reviewing ALL issues which have the %"Next 1-3 releases" during every Pre-IPM, and moving them to ~"(workspaces|webide)-workflow::prioritized" .
2. If we don’t get to them one week, we should decide how to deal with it - either agree to do them async in the next week, schedule an extra Pre-IPM, or commit to ensuring we finish reviewing them in next week’s Pre-IPM.
3. Then, during the weekly IPM, per the process defined above, these issues will be weighted and prioritized, and have their release changed from %"Next 1-3 releases" to a specific release, depending on what iteration they fall into (and we can always give ourselves a “buffer” by assuming, for our purposes, that only things slated to be completed by a certain time will be likely to be in the release, e.g., everything slated to be completed in the 2nd iteration of the month, which is a ~1+ week buffer before the actual release is cut).

See the following discussion thread for more context.

2. Pre-Iteration Planning Meeting

TL;DR:

• Async phase - Refinement:
  • Engineering Manager: Assign someone to refine each unrefined (workspaces|webide)-workflow::unprioritized issue which has the %"Next 1-3 releases" milestone using the Workspace issue template
  • Refinement Assignees: Adequately refine the issue using the Workspace issue template, then apply the refined label
• Sync phase - Prioritization: Product and Engineering leaders meet to appropriately prioritize each refined issue into the (workspaces|webide)-workflow::prioritized lane on the Iteration Planning board.

Async Phase of Pre-IPM Process - Refinement

1. Identify all issues which:
   1. Have the ~"(workspaces|webide)-workflow::unprioritized" AND
   2. Have the %"Next 1-3 releases" milestone applied (optionally include additional milestones for next 3-4/4-7 releases, if these are being used) AND
   3. Do NOT yet have the ~refined label
2. This can be done by a direct search:
   1. Workspace: direct search for Label is ~workspaces-workflow::unprioritized and Milestone is %Next 1-3 releases and Label is not one of ~refined
   2. Web IDE: direct search for Label is ~webide-workflow::unprioritized and Milestone is %Next 1-3 releases and Label is not one of ~refined.
3. Assign each of these issues to an appropriate team member to be refined, and leave a comment on the issue mentioning the team member and linking to Async Phase of Pre-IPM Process - Refinement This selection process can be whatever works for the team, but in general issues should be refined by someone who has the knowledge and availability to refine them properly and promptly. If there are questions, ask for help or reassign it to someone else.
4. The assignee should use the Workspace issue template to refine the issue. The refinement should ensure that the description of each prioritized issue is complete, and contains enough information for the team to review, understand and estimate it during the next IPM, in less than 5-10 minutes, without extensive debate/discussion.
5. There should be no TODO: comments left in the description from the template once refinement is complete. If a section from the template is not applicable, delete it.
6. If the refinement uncovers additional scope/complexity, the issue should be broken down into smaller issues, which are then refined individually. Optionally, an epic may be created to organize the work across multiple issues.

Sync Phase of Pre-IPM Process - Prioritization

1. During each Pre-IPM meeting, we will temporarily filter the Iteration Planning board on the ~refined label, so that only refined issues appear in the ~"(workspaces|webide)-workflow::unprioritized" list. Make sure you don’t save this filter to the defualt board settings
2. The goal of each Pre-IPM sync meeting will be to prioritize all of these issues into the ~"(workspaces|webide)-workflow::prioritized" list, based on their relative importance, whether they are blocking other issues, etc. They are prioritized by dragging them into the appropriate order in the ~"(workspaces|webide)-workflow::prioritized" list, with the highest-priority issues being at the top, and the lowest-priority issues being at the bottom.
3. After an issue has been moved to the ~"(workspaces|webide)-workflow::prioritized" list, it should be assigned to the current Iteration of the Iteration Cadence. We will eventually create an automation for this, but for now it must be done manually. The easiest way to do this is to search for RD in the Iteration field, and pick the top-most iteration. Then, the Iteration Cadence feature functionality will handle automatically rolling over any incomplete issues to the next iteration once the current iteration ends. Do NOT assign it to a future iteration, only the current iteration. We do this because of limitations in the GitLab Iteration feature which are incompatible with this process, and instead we rely on the GitLab Velocity Board Chrome Extension to automatically split the actual current iteration in the database into multiple future “virtual” iterations based on dynamic velocity calculations.

Explanation:

The “Pre-Iteration Planning” (Pre-IPM) meeting prepares for the Iteration Planning Meeting. It is analogous to “backlog refinement” in the standard GitLab product development flow.

During the Pre-IPM, the team will collaborate on creating/refining, organizing, and clarifying all issues which are to be prioritized for the upcoming iteration(s). This will normally involve Product and Engineering leaders on the team, but may also involve Design or other team members depending on the nature of the issues involved. The goal is to ensure that all issues which have been identified as a priority for the upcoming releases are properly refined, curated, prioritized, and ready for the wider team to briefly discuss and estimate in the next IPM.

If a single piece of work spans multiple projects/repos, there should be a separate issue created for each MR in each repo. We cannot use the tasks feature, because boards cannot display individual tasks.

QUESTION: Why isn’t there a ~(workspaces|webide)-workflow::refined phase instead of using the ~refined label?

For a few reasons:

1. We want to keep the main process and board simple and easy to understand. The three columns for unprioritized, prioritized, and done phases are intuitive and self-explanatory. Also, the movement between unprioritized and prioritized is a sync process, which ensures the team leadership are all on the same page about current priorities.
2. The refinement and prioritization process may vary among different teams that use this process in the future. Keeping the three core phases simple means that the basic process and board approach can still be used with simpler or more complex refinement/prioritization processes.
3. Finally (and most importantly from a pragmatic perspective), the implementation of the logic for velocity and iteration calculations on the board is much simpler if we enforce a standardized three-phase/three-column process and UI.

3. Iteration Planning Meeting

Process:

TL;DR: As a team, briefly discuss then estimate each prioritized issue.

1. In each the IPM meeting, all newly prioritized issues in the ~"(workspaces|webide)-workflow::prioritized" lane of the Workspace Iteration Planning board or Web IDE Iteration Planning board are reviewed by the team. The board should be unfiltered other than the standard ~"Category:Workspace" or ~"Category:Web IDE" label.
2. For each newly-prioritized issue, the facilitator reads the description, and the team briefly discusses the issue. If there are no blocking concerns/risks raised, the team collectively estimates the issue with rock-paper-scissors fibonacci scale, and the collectively agreed weight is assigned.
   1. If the discussion for a single issue goes on longer than 5-10 minutes or turns into an extended debate/discussion, this is an indicator that the issue has not been adequately refined, and should go back to the ~"(workspaces|webide)-workflow::unprioritized" list, and potentially have another issue immediately created and prioritized to do further investigation/refinement, if the refinement scope may be significant.
3. Issues which are prioritized in the upcoming 1-2 iterations should be assigned to individual(s) at this point, to ensure it gets worked on and not lost.

Async Process

TL;DR: Sometimes issues need to be weighted quickly before the offical IPM meeting. This is how we weight those issues.

Prerequisite: Add the Polly app to your Slack if you have not already.

1. Navigate to Polly application under that Apps section in Slack.
2. Select Create a Polly.
3. Select Create New.
4. Fill out creation Options:
   1. Create Question: Weight for: Add link to issue here.
   2. Question Type: Select 1-to-10 option.
   3. Choose audience: Select remote_development_async_ipm channel.
   4. Make sure “Send polly as direct message” is unchecked.
   5. Select Settings Button.
   6. Responses: Select Non-anonymous.
   7. Results: Select Show after close.
   8. Select Submit to save changes.
5. Send Polly.

Optional Steps: Template Creation

This allows you make following Async IPMs faster by standardizing the configurations. After creation, all a user needs to do is select the template from the “My Templates” section, select Use Template, and update the Issue link in the “Create Question” field.

1. Navigate to Polly application under that Apps section in Slack.
2. Select Go to Polly Dashboard.
3. Select the Polly you just made.
4. Select Controls button.
5. Select Save as Template.
6. Title Template: Remote development async ipm.
7. Ensure “Save audience with template” is checked.
8. Select Save.

Explanation:

The “Iteration Planning Meeting”, or “IPM” meeting is a weekly process where a team reviews the backlog and the current iteration status, estimates and prioritizes work for the next iteration, and uses issues as the single source of truth for discussions and progress. It is analogous to the “Weekly Cycle” in XP or “Sprint Planning” in Scrum.

The goal of the IPM is to ensure all issues for the upcoming iteration have been discussed, and estimated with weights as a team. Then, each issue will be worked on, and if there are commits to be made as part of the work, there should be a 1-to-1 relationship between the issue and MR.

The iteration cycle is one week long, and each category team maintains a separate dedicated board for tracking their progress - the Workspace Iteration Planning board and the Web IDE Iteration Planning board.

4. Assigning prioritized issues to specific releases based on calculated iterations

TODO: This can be automated in the future by adding functionality to the chrome extension. For now, it will be a manual process.

TL;DR: Assign issues to specific releases based on their calculated iteration

At this point, once all prioritized issues have been estimated, with the use of the GitLab Velocity Board Extension we will be able to know how they break down into future iterations.

Then, based on the dates of calculated iterations, we can reassign the issues from the Next 1-3 releases milestone into specific milestones.

Example Lifecycle for a Feature Issue

1. Product and Design work together to identify a new feature requirement.
2. An issue is created using the Workspace issue template. The correct labels are automatically applied by the template, so the issue shows up in the ~"(workspaces|webide)-workflow::unprioritized list of the Iteration Planning board. Note that the issue description may be incomplete/unrefined and high-level at this point.
3. Product decides the issue is a high priority, so they apply the %"Next 1-3 Releases" milestone to signal this.
4. As part of the async Pre-IPM process, someone is assigned to refine the issue, by finishing filling out the issue template, then applying the ~refined label
5. As part of the sync Pre-IPM meeting, product and engineering leadership move the refined issue to the ~(workspaces|webide)-workflow::prioritized list, in the appropriate position based on its priority relative to other issues.
6. In the sync IPM meeting, the wider team discusses and estimates the issue, and it is assigned to whoever will do the work.
7. Once the priority and weight are determined, the current velocity will tell us what iteration the issue should be completed in, and a specific release milestone can be assigned to the issue based on that.
8. The assignee opens an MR for the issue, ensures that the issue and MR are cross-referenced on the first lines of their descriptions, and begins work on the MR.
9. When the work is completely done - i.e., the MR is reviewed and merged, the feature is verified and tested in production, etc., then the issue is closed, and moved to the ~(workspaces|webide)-workflow::done list.

Relationship of Issues to MRs

We want to enforce that:

1. Every MR is owned by a weighted issue

This is in order to facilitate accurate and granular velocity calculations and issue prioritization under this process. The merge request is the atomic unit of deliverable work in most cases, so it must be represented in the prioritization and calculations by being owned by one and only one issue.

In order to enforce this via triage-ops automations (/handbook/engineering/development/dev/create/remote-development/#automations-for-remote-development-workflow), the first line of the issue should have the format: MR: <...>:

1. For new issues, the first description line should be: MR: Pending

2. Once an MR is created for the issue and work is started, the first description line of the issue should be: MR: <MR link with trailing +>, and the first description line of the MR should be Issue: <Issue link with trailing +>.

3. If the work for an issue was iteratively split into multiple MR’s, the first description line of the issue should be:

   MR:
     - <MR link with trailing +>
     - <MR link with trailing +>
   

   Each description line of the MR’s in this list should be Issue: <Issue link with trailing +>. Please note: If breaking out an issue’s implementation into multiple MR’s unexpectedly increases the scope of the work, please consider creating a new weighted and prioritized issue to capture the extra scope. This is important in order to accurately reflect scope increases, and their impact on reporting and velocity.

4. If there is NO MR associated with this issue, the first line should be: MR: No MR. However, this should be rare, because most issues should have some sort of committed deliverable, even if it is only a documentation addition or update. If it is an issue which represents a larger piece of work split across smaller issues, then it should be promoted to an epic.

QUESTION: Why does every MR need a backing issue?

• If boards and epics allowed MRs to be added and estimated as well as issues, this would not be necessary - for feature/maintenance involving an MR, we could have the MR directly represent the full lifecycle of the discussion and implementation, and not have an issue at all.
• We also cannot rely on the Crosslinking Issues feature (https://docs.gitlab.com/ee/user/project/issues/crosslinking_issues.html), because this shows ALL linked MRs that have mentioned the issue anywhere, and cannot enforce this 1-1 relationship.

📝 Ad-Hoc Work

It is normal that team members may identify issues that need to be resolved promptly prior to the next planning cycle. This may be because they are blocking other prioritized issues, or just because a team member wishes to tackle an outstanding bug or small piece of technical debt.

In these situations, it is acceptable for a team member to take the initiative to create an issue, assign proper labels, estimate it, assign it to the current iteration, and work on it, as long as it does not adversely impact the delivery of other prioritized issues. However, if it becomes large or risks impacting other issues which were collectively prioritized as part of an IPM, then the issue should be brought up for discussion with the wider team in the next pre-IPM and/or IPM.

🏋 What Weights to Use

To assign weights to issues effectively, it’s important to remember that issue weight should not be tied to time. Instead, it should be a purely abstract measure of the issue’s significance. To accomplish this, the our team uses the Fibonacci sequence starting from weight 0:

• Weight 0: Reserved for the smallest and easiest issues, such as typos or minor formatting changes, or very minor code changes with no tests required.
• Weight 1: For simple issues with little or no uncertainty, risk or complexity. These issues may have labels like “good for new contributors” or “Hackathon - Candidate”. For example:
  • Changing copy text which may be simple but take some time.
  • Making CSS or UI adjustments.
  • Minor code changes to one or two files, which require tests to be written or updated.
• Weight 2: For more involved issues which are still straightforward without much risk or complexity, but may involve touching multiple areas of the code, and updating multiple tests.
• Weight 3: For larger issues which may have some unforeseen complexity or risk, or require more extensive changes, but is still not large enough to warrant breaking down into smaller separate issues.
• Weight 5: Normally, this weight should be avoided, and indicate that the issue ideally should be broken down into smaller separate issues. However, in some cases a issue with a weight of 5 might still be prioritized. For example, if there is a large amount of manual updates to be made which will require a large amount of effort, but doesn’t necessarily involve significant risk or uncertainty.
• Weight 8/13+: Weights above 5 are used to clearly indicate work that is not yet ready to be assigned for implementation, and must be broken down because it is too large in scope to start implementing, and/or still has too many unknowns/risks. This weight is temporarily assigned to “placeholder” issues to capture the scope of the effort in our velocity-based capacity planning calculations. For more information, see “Breaking Down Large Issues”.

📝 Investigations and Breaking Down Large Issues

If a task is too large, has too many unknowns, or requires proof of concept (POC), it should be broken down into smaller investigation tasks or POC issues. These tasks help clarify the scope, reduce risks, and identify the necessary steps to proceed with implementation and ideally should fit into a single milestone.

1. Create an Investigation Issue:

   • Purpose: Research, investigate, and document or breakdown the necessary work.
   • Weight: Default to 3 for investigations, POCs, or breakdown tasks. If a different weight is needed, discuss it with PM/EM/Team stakeholders.
   • Label: Assign the ~spike label to the issue.
   • Updates: Provide an async weekly update in the investigation issue.
   • You’re allowed to adjust the weight dynamically to reflect ongoing efforts if they differ from initial estimates as new information becomes available [see Responding to change over following a plan].

2. Break Down and Close:

   • Once the investigation task is complete, document the findings and break down the work into actionable refined issues.

🧹 Follow-up issues which span multiple releases

Gitlab standards often require breaking down issues that need to be resolved in a specific set of steps that span multiple releases. Typically these are issues related to database migrations (Dropping Columns) or breaking changes in GraphQL such as “Deprecation and Removal”.

In such cases where we have pending or follow up tasks for future releases such as removing an ignore rule, removing a deprecated field from GraphQL, finalizing background migrations, etc., we must create follow up issues so we do not forget to complete the work in the future. Here is the process to follow:

Create a Followup Issue:

1. References: Link the issue to the original issue that spawned it.
2. Label: Assign these labels:
   • ~due-date-followup
   • ~refined
   • ~webide-workflow::prioritized or ~workspaces-workflow::prioritized
3. Milestone: Assign it a specific milestone - i.e Drop column (17.5) -> Followup remove ignore rule (17.6).
4. Iteration: Assign it to the current/latest iteration for Workspaces or Web IDE (this is required in order to assign a specific milestone)
5. Due Date: Assign a due date 1 week into the assigned milestone. To see the dates for the milestone, you can click “Preview” after adding the Milestone, then open the milestone link in a new tab, and find its date range at the top of the page.
6. Epic: Assign it to the WebIDE | Technical Debt/Friction or Workspaces Technical Debt Work epic.

Here’s a shortcut of label commands which you can use to easily apply this metadata.

Workspaces:

/relate #<original issue number or link>
/milestone %"<target milestone>"
/due date <one week into milestone's date, obtained from clicking on milestone link>
/label ~due-date-followup ~refined ~workspaces-workflow::prioritized
/iteration [cadence:"Workspaces"] --current
/epic &11041

Web IDE:

/relate #<original issue number or link>
/milestone %"<target milestone>"
/due date <one week into milestone's date, obtained from clicking on milestone link>
/label ~due-date-followup ~refined ~workspaces-workflow::prioritized
/iteration [cadence:"WebIDE"] --current
/epic &14656

Note that these sorts of issues which we are required to defer until future releases should not be confused with “tech debt” work that we are choosing to defer. That is why they use the following process involving milestones, custom labels, and due date reminders to ensure that we do not forget to follow up and complete them.

🍨 Handling Issues Outside the Process

Certain group::remote development issues may be categorized under the (workspaces|webide)-workflow::ignored label. These categories include:

1. QA-Owned Issues:
   • Issues owned by QA that may not require the standard Workspaces process.
2. PM-Owned Issues with type::ignore:
   • Issues owned by Product Managers marked with type::ignore, such as reporting, blogs, OKRs, etc.
3. Long-Lived Security Issues:
   • Security-owned issues with extended timelines that don’t align with the typical Workspaces workflow.

This approach ensures that these types of issues do not have an undesired impact on our velocity, and that our Workspaces process remains streamlined while accommodating different issue categories that may not fit the standard workflow.

👏 Communication

The Remote Development Team communicates based on the following guidelines:

1. Always prefer async communication over sync meetings.
2. Don’t shy away from arranging a sync call when async is proving inefficient, however always record it to share with team members.
3. By default communicate in the open.
4. All work-related communication in Slack happens in the #g_create_ide channel.

⏲ Time Off

Team members should add any planned time off in Workday, so that the Engineering Manager can use the proper number of days off during capacity planning.

🤙 Ad-hoc sync calls

We operate using async communication by default. There are times when a sync discussion can be beneficial and we encourage team members to schedule sync calls with the required team members as needed.

🔗 Other Useful Links

🏁 Developer Cheatsheet

Developer Cheatsheet: This is a collection of various tips, tricks, and reminders which may be useful to engineers on (and outside of) the team.

🤗 Fostering Wider Community Contributors

We want to make sure that all the fields of the Create:Remote Development team are approachable for outside contributors. In this case, if issues should be good for any contribution it should be treated with extra care. Therefore have a look at this excellent guide written by our own Paul Slaughter!

Cultivating Contributions from the Wider Community: This is a summary of why and how we cultivate contributions from the wider community.

📹 GitLab Unfiltered Playlist

The Remote Development Group collates all video recordings related to the group and its team members in a playlist in the GitLab Unfiltered YouTube channel.

Create:Remote Development Error Budget

• https://dashboards.gitlab.net/d/stage-groups-detail-ide/stage-groups-ide-group-error-budget-detail?orgId=1
• https://dashboards.gitlab.net/d/stage-groups-ide/stage-groups-ide-group-dashboard?orgId=1

Automations

Automations should be set up via triage-ops if possible.

Other more complex automations may be set up in the Remote Development Team Automation project.

Automations for Group Workflow

Ideally we should automate as much of the Remote Development Planning Process workflow as possible.

We have the following automation goals for this Workflow. Unless otherwise noted, these rules are all defined in the triage-ops policies/groups/gitlab-org/ide/remote-development-workflow.yml config files.

TODO: None of these are set up yet for the Web IDE category and webide-workflow::* labels yet - there is an issue for this. These need to be set up, and the references to “workspace” in the table below should be updated accordingly to also include “webide”.

View page source - Edit this page - please contribute.