Migrating PRODUCT Guides to New Repo

[edwardsarah]

Overview

We need to move all existing guides to the new repository for guides and templates (knowledgebase-content)

Prerequisite

You need to have

• Manager access to the following drives
  • CoP Google Drives
  • KB-content drive
• Admin access for the repos the issues are in

Action Items

Use steps 1-5 on the Guide below to prep all guides related to PRODUCT for migration from the CoPs to knowledgebase-content

• [ ] Do steps 1-5, tracking links to each issues worked on in a comment below
• [ ] Reach out to Sarah in the guides slack channel by sending her a link to the comment with the issues completed
• [ ] Once given the OK, use steps 7-11 to migrate all guides related to PRODUCT to knowledgebase-content
• [ ] Check wikis/other resources for references to guides by numbers or names, so no links end up broken

Resources/Instructions

• Repo: knowledgebase content repo
• Repo Product CoP Repo
• Google Drive: Knowledgebase-content
• Project Board: Guides: Knowledgebase Content Tracker
• Form: Guides Migration Google Form
• Spreadsheet: New Guide Tracker (WIP)
• Guide: How to Move a Guide to a New Repo

[edwardsarah]

List of Issues to Check Post-Transition:

• [x] https://github.com/hackforla/guides/issues/48
• [x] https://github.com/hackforla/guides/issues/57
• [x] https://github.com/hackforla/guides/issues/59
• [x] https://github.com/hackforla/guides/issues/70

[edwardsarah]

Notes about Migrating Guide Issues from CoPs to Knowledgebase-content

Github Doc - Transferring an Issue to Another Repository

• from this doc, it looks like we won't have the issue we assumed we would have with losing references to the original issue. The link will just redirect
• If someone references the issue by name or issue number, they can look it up in the guides audit spreadsheet, which we can preserve
• Assignments will be preserved. Still a good idea to check in with assignees so they know what's going on, and can be removed if they are no longer working on their guide.

Greater issue: migrating all of the associated documents

• How big of a problem is this?
• Potential roadblock is permission to view necessary files. Would likely need an additional way to track which documents cannot be migrated and how to manage that

[edwardsarah]

Migrate product guides from CoPs to knowledgebase-content

Checklist for Moving a Guide

Before Moving

In the guide issue you are going to move

• [ ] Copy all of the content from the body of the issue into a new comment on the same issue

• [ ] Replace the body with the new template text for guide issues

  ### Overview
  We need to create a guide to using size labels so teams can accurately assess how long tasks should take to complete.
  
  ### Action Items
  The phases in the guide-making process are listed below. Each phase displayed in blue is linked to a wiki page with instructions on how to complete that phase. Open the wiki page in a new tab, copy the instructions for each part into the section labelled 'Tasks' at the bottom of this issue, and complete each task listed.
  - [ ] [Gather Examples Solo](https://github.com/hackforla/guides/wiki/How-to-Gather-Examples:-Solo) (open in a new tab)
  - [ ]  [Gather Examples Collaboratively](https://github.com/hackforla/guides/wiki/Phase-2-%E2%80%90-Gather-Examples-Collaboratively)
  - [ ]  [Create a Guide Draft](https://github.com/hackforla/guides/wiki/How-to-Draft-a-Guide)
    - [ ]  If needed, create a template
  - [ ]  [Have your guide peer reviewed](https://github.com/hackforla/guides/wiki/Peer-Reviews-for-Guides)
  - [ ]  [Present your guide for leadership review](https://github.com/hackforla/guides/wiki/Submitting-Your-Guide-for-Leadership-Review)
  ### Resources/Instructions
  ### Projects to Check
  ### Tasks
  - [ ] This is where you will copy instructions from the wiki page for the step you are currently on.

• [ ] Screenshot the labels and its current project board info

  • Example:

    

  • [ ] Add this screenshot in another comment

• [ ] Identify all documents created for this guide issue and add them to a comment
  • [ ] Check each document for relevance (briefly - is there content in them, and does it seem useful?)
    • [ ] If useful, add this note

    • This document will need to be moved to the knowledgebase-content Google Drive

  • [ ] If documents cannot be opened
    • [ ] and the document exists (don't ask for write access), include the link in your comment and this note

    • Unable to view this document while moving this issue

    • [ ] and the document dosen't exist, include the link in your comment and this note

    • This document looks like it has been deleted

• [ ] If someone is currently assigned to the issue, @ them in a comment with this note

  This guide issue is moving to the knowledgebase-content repo. If you would like to maintain access, please fill out the [Google Drive Access Form](https://forms.gle/vnKRqprNYJUG5ET69). 

• [ ] Move the guide to the knowledgebase-content repo
  • [ ] Click Transfer Issue (see image below)
  • [ ] Choose a repository -> knowledgebase-content
  • [ ] Transfer issue
  • This may take a few minutes to complete!

After Moving

• [ ] Add the correct labels
  • [ ] CoP: the CoP label should reflect the community of practice the issue was transferred from
  • [ ] Size: missing
  • [ ] Milestone: missing
  • [ ] Phase & Status: see below
• [ ] Add to project board
  • [ ] Most guides will be added to the Prioritized Backlog column
  • [ ] if the guide's current assignee has responded saying that they are still working on the issue, put it in 'In Progress'
  • [ ] if the guide is in the peer or leadership review stage, add to 'Ready for Review'
• [ ] Add new issue number to Guides Audit Spreadsheet in the New Issue No. column.
• [ ] Transfer any documents to the knowledgebase-content drive
  • [ ] If documents cannot be moved, make a note of this in a comment on the issue
  • [ ] Create shortcuts in relevant CoP folders

[ExperimentsInHonesty]

@edwardsarah please

• [x] link the drive created to the resources of this issue.
• [ ] explain what we are checking these links for https://github.com/hackforla/guides/issues/139#issuecomment-1731281307
• [x] Add the link to the guides audit spreadsheet to the resources section of the issue

Also we need to define how to do the following:

• [ ] Pick the Guide
• Evaluate if it's a proper guide before moving it. If it needs to be split into multiple guide issues, is not useful as a guide topic, or is a duplicate, this should be sorted out before the transition takes place.
• [ ] In a comment, make note of where the guide is in the process (ex. Gather Examples Solo) so the proper labels can be added

[edwardsarah]

explain what we are checking these links for https://github.com/hackforla/guides/issues/139#issuecomment-1731281307

One of the potential issues we raised with migrating existing guides to a new repo is whether it would break references to that guide elsewhere. For example, if a guide issue was linked in a wiki page in its original repo, and we moved it to the new repo, would the link still work? The GitHub documentation suggests any old links will redirect to the new link, so this won't be an issue.

[edwardsarah]

explain what we are checking these links for https://github.com/hackforla/guides/issues/139#issuecomment-1731281307

There are a number of issues in the Guides team repo that refer to or are dependent on the current structure of guides, with each CoP having its own board for guides. We will need to review those issues once the guides have been migrated to make sure we close any that are no longer relevant.

[edwardsarah]

Guidance on Picking Correct Labels

This is meant to act as a general structure for how to decide what labels a guide issue should receive. It will likely need to be updated with more specific criteria as we migrate guides and deal with edge cases.

Non-Guide-Specific Labels

COP The CoP label should reflect the CoP that the guide issue was migrated from. If, given your best judgement, there is another CoP the guide issue is relevant to, add this as well. Size Size labels are used here the same way they are used in other HfLA repos, and reflect how much time it will take to complete the issue. Milestone Bonnie will sort the guides by milestone. Just add the milestone: missing label

Guide Specific Labels

Begin by checking the comment you created previously with the screenshot of the issue's previous milestones and labels. This will give you some understanding of where in the process the guide was, though it is not always perfect.

Phase & Status

1 - Gather Examples Solo

• The guide issue has no examples at all AND is a guide that requires them (status 1.1-1.4)
• The guide issue has some examples, but not from all teams (status 1.1-1.4)

2 - Gather Examples Collaborative

• The guide issue has examples from all teams (or notes indicating that the team has been checked and no example has been found) BUT no indication that they've talked to anyone from those teams (status 2.1)

3 - Drafting a Guide

• The guide issue concerns a process or practice with only one way of doing things, and so does not need examples from teams (if no draft, status 3.1)
• Examples have been gathered, but there is no guide document yet (status 3.1)
• There is a draft guide, but it is incomplete (status 3.2)
• There is a complete draft guide, but it needs reformatting (status 3.2)
• There is a draft guide, but it needs a template (status 3.3)

4 - CoP Peer Review

• There is a complete draft, and it is properly formatted (status 4.1)
• The owner of the guide issue has commented in the issue that it is ready for review, and a basic check of the document shows that it is a complete guide with proper formatting (status 4.1)
• Feedback has been given in a previous comment, but not incorporated into the guide document (status 4.2)

[aymarmsba]

Left of at the "Add to project board" where the project board "knowledge base" specific guide tracker was not showing for me

[edwardsarah]

Moving instructions into a working document, still a work in progress at the moment: How to Move a Guide to a New Repo

[edwardsarah]

Document updated with more clear instructions on labelling guide issues.

[aymarmsba]

I was not able to move any files to the knowledge base content drive since I didn't have access to move files.

[fchan218]

Date: 2024-10-04

1. Progress: Migrated 13 issues and there is approx 44 issues left to migrate
2. Blockers: On the Excel sheet, some topics do have have issue # linked but they have links to wiki page. Will those topics need to be migrated as well?
3. Availability: 2-3 hours/week
4. ETA: 1-2 month
5. Pictures (if necessary): None

[ExperimentsInHonesty]

@fchan218 the items with no issues to migrate, that have a wiki page, need to have an epic issue to create new guide issues and link the wiki in the resources for the person who will create the guide. Please add reviewing the epic to our next agenda, so we can approve and move it to the prioritized backlog.