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 Jul 25, 2019 · 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

If I am developing on develop

After checking out the repo, make sure to run init.sh or init.ps1. This checkouts 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

If I am developing on develop

After checking out the repo, make sure to run init.sh or init.ps1. This checkouts 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: feature, bugfix, docs, hotfix, and experimental (see below). Our CI pipelines filter branches based on these prefixes to enforce this practice.

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

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.

Experimental Branches

For larger features that are best reviewed in chunks, should have an experimental branch established. The intention of an experimental branch is that individual PRs are made into the experimental branch and when its complete, can be merged into develop with minimal review (as all the components should have been reviewed before). It is also possible for an experimental branch to be dropped.

Note that branch protections should be turned on for experimental branches. This ensures that the review and CI workflow is enforced for PRs into it.

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. 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, respond with questions: use cases, potential other solutions, etc.

Tracking Issues

A tracking issue is an issue opened by a maintainer to track the status of a large feature or a known issue. Examples: #676.

A tracking issue should contain:

  • A description of the feature / bug.
  • In broad strokes, the remaining issues/questions to be resolved about this feature / bug.
  • Relevant labels (T: Tracking is mandatory)
  • A reference to the internal JIRA ticket.

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.

Milestones

Another way of categorizing and filtering PRs and issues is to use Milestones. These Milestones correspond to a Fix Version in JIRA and eventually to a Release in Github.

  • PRs should have a milestone added once it is known which release the PR will land
  • Issues should have milestones added once it is known which release the issue will be closed in.

Roadmap

We publish a public roadmap to let users know when features are ready to land. The first three columns are buckets of features that are in the various stages of development:

  • In Research - These features are still being researched for feasibility, use cases, and existing solutions. Features listed here may still be speculative and are not guaranteed to be done.
  • In Design - These features are still in the design phase and implementation has not begun.

The columns to the right of these three represents specific releases. Releases are either planned (denoted with [Planned]) 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.
  • Misc Git CLI tools - a little shameless self-promotion. Two tools that make swapping branches and cleaning your local repositoryt easier.

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