# OMI Github Strategy

[](https://hackmd.io/msSrKU3NQv2QO8_aU5IhHQ)

###### tags: `OMI`

This plan highlights how we can use github to handle the majority of our working processes. Github allows us to reduce the number of tools we are using, and keep everything in one place.

It can be challenging for newcomers to get involved, we want to ensure that everyone understands where work is happening, and establish a reliable place for future work to live. The process is iterative, and by no means "perfect". If you have alternatives, please attend a backlog refinement session!

## Spinning up a new Repo for a working group

We operate in working groups, to divide work based on themes of interest and availability. If the Metaverse is for anyone, we believe that anyone can add value to the Metaverse. Our working groups have their own working agreements, with meeting times decided by those who attend the working groups. Backlogs, discussions, and agile ceremonies are decided on at the group-level, as we have contributors from all around the World.

The best way to get involved is to reach out to the working group directly. Our existing working groups are on various levels of maturity. Some have been working for months and have working agreements in place, and take detailed notes each week. Others meet more ad-hoc or are brand new, and may not have formalities documented yet. You are encouraged to get involved with any group that fits your knowledge, skills, abilities, and interests, and help shape the culture of that working group collectively.

To create a new working group, you can follow these [OMI Working Group Minimum Requirements](https://github.com/omigroup/omigroup/blob/main/WORKING-GROUP-MIN-REQUIREMENTS.md).

Once we vote to create a new working group, that group meets for the first time and hashes out some of the basics: when do we meet, how do we track progress, what are our team norms/expectiations? You can repeat this kickoff milestone from the MSF-delegates repo:

- example [onboarding milestone](https://github.com/omigroup/MSF-Delegates/milestone/1)
- 
<details><summary>sample milestone language</summary>
<br />

> Let's get you all set up with a place for tracking any known tasks, or initiatives as they relate to OMI's involvement with MSF! Don't sweat... this can be easy!
>
> We will get you set up with a readme, connect your discord channel, and in your next meeting, you can decide if you want a backlog or not. (It's not mandatory! But if you do decide to create a backlog for tracking work, make sure someone is prepared to groom periodically :smile:)
>
> Note: If you complete tasks in the milestone, you can see the progress bar advance. It's a great way to populate issues around the desired outcome (rather than arbitrarily filling up a kanban board with everything that comes to mind)

https://github.com/omigroup/omigroup/blob/main/WORKING-GROUP-MIN-REQUIREMENTS.md

</details>

## Github Discussions:

Sometimes we need to talk something through together. When you need group insight and collaboration, slack can get quick answers but often key insights are lost to day to day communications and noise. Documenting our process doesn't have to be a burden put off until after you are finished. Documentation can be captured as you go, by adopting a few simple processes.


### Uses:

- When you don't have a specific problem or solution identified and need to talk it out or brainstorm ideas
- Create one as meeting notes at the start of any meeting and collaboratively comment observations and links and demos in the comments.
- :star: Even better: Create a discussion with just the agenda for an upcoming meeting. Then take notes together in the comments on meeting day.
- When you want to reflect on a workshop
- When a official artifact is in draft mode
>note: you can convert comments from discussions into backlog issues. A discussion can quickly create a list of backlog items _while you brainstorm_.

## Backlogs / Kanban boards / Github "Projects"

At times, we must juggle a lot of things at once :juggling: and this can cause confusion, spinning tires, and analysis paralysis. Just as someone gets up to speed, a new person joins and it starts over again.

Use the backlog(s) which are called _"Projects"_ on github. There are Projects beta, and Projects (non-beta) versions of their boards.


>note: There are now github projects, AND "projects-_beta_" boards. I recommend using the standard github projects boards for now, as the _beta_ boards are brand new. However, we track [our holistic backlog using the new beta board method here](https://github.com/orgs/omigroup/projects/7/views/2).

### Purpose of the backlog:
We need a place to reliably put our **known problems to solve,** prioritize work, and track progress. An item is moved from the to-do column, to the in progress column when work for that item starts. If the ticket becomes blocked, or is ready for review, the card moves to that column. And upon approval, or termination, the issue will move to the "done" column.

This allows us to track any amount of work, and flesh out our ideas as we go.


### We have multiple Projects / Backlogs

OMI is a fluid group consisting of a number of working groups that self-organize around common goals. These backlogs help organize this work at the working-group level, and we can syndicate all active issues on the [OMI Holistic Backlog](https://github.com/orgs/omigroup/projects/7/views/2) to see all in-flight issues in one place.

If someone couldn't make it to a meeting this week, having a place to reliably see what work is in flight, who is doing what, and how to get involved is critical to a self-governing and organic group like OMI.

Think of repos like sandboxes for themes of work or working groupos. So far we have backlogs in `github.com/omigroup/omigroup` for managing general tasks, `github.com/omigroup/website` for tracking website tasks and issues, `github.com/omigroup/gltf-extensions` for managing the workflows of the gltf extensions group, and more.

You can actually create a new project by clicking `New Project` in the "Projects" menu of any repo.

### Holistic Overview:
This is a holistic backlog for general operations and tracking key tasks across all our working groups repos and projects. This backlog lives at the Org level at `github.com/omigroup/` and can be accessed by clicking Projects in on the omigroup organization page. The beta version has both a list-view AND a Kanban board view.
#### Start at the main org page OMIgroup/ (not omigroup/omigroup :rotating_light:)
#### Kanban View like Trello
#### List view like ProductPlan

### How to use a Github Projects backlog
>#### To add a card click the `+` symbol at the top right of the column

#### Add a Note

Notes on the backlog can be easily identified with white text.


There is no clickable link, just text and markdown. You can add tags to a note, add markdown, and quick reminders. Notes are like quick reminders. Something like "remind team to submit daily balance scores" or "schedule first interview".

>:rotating_light: If you do not have access to add tasks or issues to the backlog, and feel you need too, please reach out to mrmetaverse for github permissions.

#### Create an issue

Issues are a larger chunk of work, that you may need to discuss, track, or breakdown. Issues can be easily identified by having blue text which can be clicked.


Maybe you already know the work that needs to be done, so you may write an issue like you would write a user story, with acceptance criteria and definition of done.

In other cases, you may have to convert a comment on a discussion, or a note on a backlog convert it into an issue. Issues allow you to assign tags, add owners, add additional details, discuss in comments, and more.

Issues are often used to call out feature requests, bug reports, and requests for help. Issues are fodder for pull requests and recommendations.

At any time you can click on `Go to issue for full details` to open up that issues page, and see comments, changes, files, tags, and other information:


#### Submitting a formal proposal / issue

We have established 4 templates at the present moment in our `omigroup/omigroup` repo.


##### Call for participation:

If you have a clearly defined plan of work, and want to rally a team to support the effort, you may submit a "Call for Participation." This issue will be reviewed by the OMI group in our weekly meeting, where you can elaborate on your needs, the reason it is worth pursuing, and any other relevant information. The group will vote on if it's something we want/have capacity to pursue.

##### Meta Issue:

Is there an issue concerning OMI itself? Something we can improve, or a new process we should consider?

##### Specification Proposal

Used to propose a technical specification. This is where new protocols are formally born. (To see the full submission process, please see [process.md](https://github.com/omigroup/omigroup/blob/main/PROCESS.md) on the `omigroup/omigroup` repo)

##### Work Item Proposal

Maybe you have other non-specification work items that you think we need to work on. You may propose an issue using this template, to have your item(s) added to the primary backlog.

#### Referencing Issues in other issues

Sometimes you'll create issues which are stories related to a larger issue which might be an epic. For example, "Create Style Guide" might be an epic, and "Identify Colors" might be a story associated with that epic.

If you create another issue like "Design Button", just mention this ticket by typing `#29` (or whatever the issue number of your epic is) and pressing enter.

That should reference this Style guide ticket in your new "Design Button" ticket, and it will automatically add a reference to that new ticket in the comments of this Style Guide ticket. Like so:


In the "Identify What needs to be Done" ticket #23 I mentioned the Overarching "Style Guide" ticket #29.

#### Adding Tags / Labels:

You can tag issues based on which objective or core value they are a part of, like `documentation` or `Maintain Sustainable Innovation` and you can also add tags to fit your needs.


To add a Tag, click the blue text of a card of interest. A tray will slide out on the right side.


You may then assign tags by searching and clicking on the ones that are relevant.


#### Adding issues to multiple projects/backlogs:


If you are working on a specific working group like `omigroup/website`, you will be working from the [OMI Website Groups Backlog](https://github.com/omigroup/website/projects/1). However, when you add a new item of interest, it is helpful to add that issue to the [OMI Holisic backlog](https://github.com/orgs/omigroup/projects/2) as well. This helps track all of the work in flight across both projects.

#### Converting a discussion comment into an issue

Discussions are a great way to generate multiple responses. Maybe you create a discussion that asks "How can we identify which problems matter most to the client?" The team can respond in comments with suggestions like, "what if we call them?" or "How about a LDJ workshop?"


You can convert that comment into a new issue on the backlog:


Just select `Reference in new issue` and add some context for your new issue.


#### Converting a backlog note into an issue

On our projects boards / backlogs, we can quickly add notes for reminders. But maybe that escilated in complexity. Maybe you had a note to `remind the team of new meeting time Friday at 6pm`. You go to complete that task, and the team responds negatively. "What do you mean we should meet on Fridays at 6? I think we should talk about this".

Well you can't have a discussion within a note, only issues and discussions. Since this has turned into a bigger topic, you can get a lot of responses async in comments of an issue. To convert a note to an issue, click the `...` at the top of the note:


and select `Convert to issue` and add a description.

## Milestones

[Milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) focus on outcomes, and make sense of outputs. Github Milestones are a great way to establish an Epic, or larger chunk of work, and break down the tasks and issues that are associated with it. Milestones can have a description (who is this for, why are we here, what do we hope to accomplish), a due date, and even a built in %-complete progress bar.

Each issue in the Milestone is it's own page, with its own ability for commenting and referencing other issues. Milestones help organize and track themes of work in a more accessible way.


### How milestones help:
To better manage your project, you can view details about your milestone. From the milestone page, you can see:

- A user-provided description of the milestone, which can include information like a project overview, relevant teams, and projected due dates
- The milestone's due date
- The milestone's completion percentage
- The number of open and closed issues and pull requests associated with the milestone
- A list of the open and closed issues and pull requests associated with the milestone

Additionally, you can edit the milestone from the milestone page and create new issues that are, by default, associated with the milestone.

### Creating a milestone

To create a milestone, follow [these github recommended steps](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests).


## the README

The [omigroup/OMIgroup readme](https://github.com/omigroup/OMIgroup) is a source of truth. Often, a readme is used to explain how to pull code, run and test code, and submit changes.

In our research efforts, a readme is a great place to summarize our work. Who are we serving, Why are we here, What are our objectives, and How do we plan to measure progress. One brief portal that helps newcomers get up to speed, and understand where and how to get involved.


## Adding files

You may upload files directly into the repo. First, select which folder you want to add files to:


You will be brought to a new page. You can upload directly here, or to the artifacts folder by click `assets`.

Once you are where you want to add your file, just click `Add file` next to the "Go to file" button.


You may then add a file name, and description. This is a change to add links, or additional comments as well.

:rotating_light: Avoid committing directly to master. Instead select "create a new branch for this commit and start a pull request. Learn more about pull requests." and click `propose changes` when finished


## Creating a new repo

Developers may need to establish a new repo entirely. Maybe the project turns into 3-5 other product lines or solutions. In this case, you can still cross post issues on multiple backlogs, and link to these repos in readmes and documentation.

We have a template repo for new working groups that you can clone once your working group kicks off.

## Link to Discord

We use github to discord integrations to alert working group discord channels of changes to their associated and subscribed working group github repos.

You can track all OMI GitHub changes in the discord channel #omi-github

## The wiki
>We do not currently use the wiki in our OMI github.

Once a discussuon is complete, or a issue has been closed, a final artifact may have been created. We can save these artifacts, and key insights in our `omigroup/omi` Wiki. Like a final draft for future readers to get up to speed, and for rapid reference on the fly.

- User groups
- Key problems to solve
- Product vision
- Working agreement

## What if we hate it?

Use it! Have conversations, reflect on if its working, lay breadcrumbs for future team members. But above all, we must try. Now at this point, I challenge the team to add your unknowns to the backlogs, and ensure that you have all you need defined.