Skip to content
This repository has been archived by the owner on Jan 18, 2022. It is now read-only.

Maintainer's Guide

Jump to bottom
Jamie Brynes edited this page Feb 5, 2020 · 17 revisions

This guide is aimed at maintainers of the repository - not external contributors or users.

Local Workflow

Since the introduction of NPM packages, the local workflow has changed a little bit.

gdk-for-unity

After checking out the repo, make sure to run init.sh or init.ps1. This downloads the Worker SDK packages.

gdk-for-unity-fps-starter-project

I am developing on develop

After checking out the repo, make sure to run init.sh or init.ps1. This checks out the version of the gdk-for-unity repo specified in the gdk.pinned file and symlinks the packages across.

I am investigating a bug report on a specific version or doing release QA

Don't hit init.sh. Let the UPM package resolution mechanism pull the correct packages.

gdk-for-unity-blank-project

I am developing on develop

After checking out the repo, make sure to run init.sh or init.ps1. This checks out the version of the gdk-for-unity repo specified in the gdk.pinned file and symlinks the packages across.

I am investigating a bug report on a specific version or doing release QA

Don't hit init.sh. Let the UPM package resolution mechanism pull the correct packages.

Branching Strategy

This applies to the gdk-for-unity, gdk-for-unity-fps-starter-project, and gdk-for-unity-blank-project repositories.

These repositories currently follow the master-develop workflow, where master is pinned to the latest release and develop is the branch under active development.

All PRs should be aimed at and merged into the develop branch.

Day to day workflow

When working on a feature, bug fix, etc, make a branch off of the develop branch with an appropriate prefix:

git checkout -b feature/my-feature develop

Appropriate prefixes include (but are not limited to!): feature, bugfix, docs, hotfix, and chore.

When you are happy for your branch to be reviewed:

  1. Open a PR against the develop branch.
  2. Fill in the PR template sections (where appropriate).
  3. Select 2-3 reviewers depending on the size/complexity of your PR.
  4. Add relevant labels and milestone.

Docs Workflow

Note: This workflow will change very soon after the documentation port is completed.

Currently, the Improbadoc source for our website documentation is stored in a separate branch to the code source. There are two docs branches that you need to know about. docs-current and docs-next.

  • docs-current: This branch contains what is currently live on our website. Roughly equivalent to master. The only PRs permitted to be merged to this branch are: hotfixes and docs-next at release time. (Note that this is enforced by you, the maintainer).
  • docs-next: This branch contains the next version of the docs to be published at next release. All PRs are permitted to be merged to this branch.

The following describes the workflow for each type of change.

I have a change to the docs for the next release

  1. Branch off of docs-next.
git checkout -b docs/my-feature docs-next
  1. Make changes and open PR into docs-next.
  2. Get approval from at least one tech writer.
  3. Merge.

I have a hotfix to the docs that are currently live.

  1. Branch off of docs-current.
git checkout -b docs/my-hotfix docs-current
  1. Make changes and open PR into docs-current.
  2. Get approval from at least one tech writer.
  3. Merge.
  4. Deploy docs-current (docs on this coming soon ™️).
  5. Branch off of docs-next.
git checkout -b docs/my-hotfix-next docs-next
  1. Cherry pick the squashed merge commit from docs-current. You may need to resolve conflicts. To find the commit hash:
git log docs-current

To cherry-pick the commit:

git cherry-pick <commit-hash>
  1. Open PR into docs-next.
  2. Merge into docs-next.

Labels

We use labels to identify and filter PRs and issues. The section details the types of labels we use:

Area labels

These are labels in the form of A: *. These labels are meant to denote what area of the product this issue or PR pertains to. Examples include: A: core, A: mobile, A: codegen.

Status labels

These are labels in the form of S: *. These labels are meant to denote what the status of a PR or issue is. Examples include: S: being-considered, S: blocked, S: inactive-closed.

Type labels

These are labels in the form of T: *. These labels are meant to denote the type of a PR or issue. Examples include: T: bug, T: feature, T: documentation.

Other labels

There are also the size/* labels which are automatically placed on PRs by prow bot. These denote the size (in line count) of a PR.

Issues

There are a few types of issues that may be encountered. Each section below details the rule of thumb to follow when an issue of this type is created.

Bug Reports

If a user opens a bug report:

  1. Mark the issue with the T: Bug label along with a relevant area label.
  2. Open a corresponding ticket on JIRA and add a github_issue label to the JIRA ticket.
  3. Comment on the issue that This is being tracked internally as UTY-wxyz.
  4. (Optional) If applicable, request more information: reproduction steps, version information, etc.

Feature Requests

If a user opens a feature request:

  1. Mark the issue with the T: feature, and S: being-considered label along with a relevant area label.
  2. Reach consensus within the team whether we will accept this feature request. If yes, proceed. Otherwise close the issue with the appropriate label.
  3. Open a corresponding ticket on JIRA and add a github_issue label to the JIRA ticket.
  4. Comment on the issue that This is being tracked internally as UTY-wxyz.
  5. (Optional) If applicable, respond with questions: use cases, potential other solutions, etc.

Known Issues

A known issue is an issue opened by a maintainer to let users know about a known issue and track its status. Examples: #955

Template:

**Affects:** The release that this known issue affected
**Internal Ticket:** a linked ticket reference.

---

#### Description

A short description.

#### Workaround

How to get around this issue if possible.

Roadmap

We publish a public roadmap to let users know when features are ready to land.

The Coming Up column describe features that are in research / planned that may be released. These are not strictly ordered.

The columns to the right of the Coming Up column represent specific releases. Releases are either in progress (denoted with [In Progress]) or done (denoted with [Done]).

In the column of each release are features that were/are going to be released in that release. Until a release has been completed, features may slip from release to release.

Once we have a planned release date for a release, we should add a card to the top of the column stating that the release is provisionally planned for a certain date.

When a release is released, we should edit the card stating the release date to "Released on x/y/z" with a link to the release notes.

Tools

The following is a list of tools that you may find useful.

  • Hub CLI - a CLI for interacting with Github. This is optionally used with the ci/generate-api-docs.sh script.
  • Buildkite CLI - a CLI for interacting with BuildKite. This allows you to run and debug pipelines locally on your machine.

Git Aliases

The following are some aliases you may find useful. See Git Aliases for the details of adding these.

  1. ff = pull --rebase origin
    • This alias is useful for fast forwarding your branch's base.
    • Example usage: git ff develop to fast forward your branch against develop.
  2. lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit
    • This alias gives you a more legible and compact git log. For example:
    jamiebrynes /c/Workspace/Develop/docs  (docs/toc-tweaks)
λ git lg -n10
* 8ec1009e - (HEAD -> docs/toc-tweaks, origin/docs/toc-tweaks) remove broken toc (17 hours ago) <Jamie Brynes>
* 5d30c377 - feedback (17 hours ago) <Jamie Brynes>
* aaa6386c - (docs/tutorial-tweaks) tutorial tweaks (18 hours ago) <Jamie Brynes>
* 5545357d - (origin/docs/cleanup, docs/cleanup) tweak (18 hours ago) <Jamie Brynes>
* ec42e6e8 - update images (2 days ago) <Jamie Brynes>
* 69e5a12b - more changes (2 days ago) <Jamie Brynes>
* 6bb14933 - more changes (2 days ago) <Jamie Brynes>
* c7991d83 - build workers (2 days ago) <Jamie Brynes>
* ce07b927 - more setup changes (2 days ago) <Jamie Brynes>
* 4f2c3ff2 - setup changes (2 days ago) <Jamie Brynes>
Clone this wiki locally