sync

Documentation

Index

• func MakePRs(f *Flags) error
• type AzDOVariableFlags
  • func BindAzDOVariableFlags() *AzDOVariableFlags
  • func (a *AzDOVariableFlags) SetAzDOVariables(prNumber, upToDateCommit string)
• type ConfigEntry
  • func (c *ConfigEntry) PRBranchStorageRepo() string
  • func (c *ConfigEntry) TargetBranch(upstream string) (string, error)
• type Flags
  • func BindFlags(workingDirectory string) *Flags
  • func (f *Flags) MakeGitWorkDir() (string, error)
  • func (f *Flags) ParseAuth() (gitcmd.URLAuther, error)
  • func (f *Flags) ReadConfig() ([]ConfigEntry, error)
• type GitAuthOption
• type SyncResult
  • func MakeBranchPRs(f *Flags, dir string, entry *ConfigEntry) ([]SyncResult, error)

Functions

func MakePRs

func MakePRs(f *Flags) error

Types

type AzDOVariableFlags

type AzDOVariableFlags struct {
	SetVariablePRNumber       *string
	SetVariableUpToDateCommit *string
}

AzDOVariableFlags is a set of flags that a sync command runner can set to make sync emit AzDO Pipeline log commands to return the results of a sync operation into a form that can be used in later steps in the pipeline. See BindAzDOVariableFlags for flag descriptions.

func BindAzDOVariableFlags

func BindAzDOVariableFlags() *AzDOVariableFlags

BindAzDOVariableFlags creates a flags struct that contains initialized flags.

func (*AzDOVariableFlags) SetAzDOVariables

func (a *AzDOVariableFlags) SetAzDOVariables(prNumber, upToDateCommit string)

SetAzDOVariables prints logging commands to stdout to assign the output variables if the variable name flags have been set, otherwise does nothing.

type ConfigEntry

type ConfigEntry struct {
	// Upstream is the upstream Git repository to take updates from.
	Upstream string
	// UpstreamMirror is an optional upstream-maintained mirror of the Upstream repository.
	// Specifically, for Upstream 'https://go.googlesource.com/go', the UpstreamMirror is
	// 'https://github.com/golang/go'.
	//
	// When updating a submodule, sync checks both repos and only updates to a version that is in
	// both. This ensures our dev process doesn't have a strong dependency on one copy of upstream's
	// code or the other, and makes it reasonable to point the submodule at the GitHub mirror of Go
	// by default, which has a better appearance in the GitHub UI for a submodule: a clickable link.
	//
	// When merging a fork, the check is skipped. A fork inherently mirrors the upstream code, so
	// there is no reason to look for a common version and hold back.
	//
	// If UpstreamMirror is not defined (default), the update simply uses the latest version of
	// Upstream.
	UpstreamMirror string

	// Target is the GitHub repository to merge into, then submit the PR onto. It must be an https
	// github.com URL. Other arguments passed to the sync tool may transform this URL into a
	// different URL that works with authentication.
	Target string
	// Head is the GitHub repository to store the merged branch on. If not specified, defaults to
	// the value of Target. This can be used to run the PR from a GitHub fork.
	Head string
	// MirrorTarget	is an optional Git repository to push the upstream branch to. All mirroring
	// operations must succeed before sync continues with this sync config entry. The mirror target
	// is intended to be an internal repo, for reliability and security purposes. Mirrored branches
	// use the same name as they have in Upstream, ignoring BranchMap.
	MirrorTarget string

	// BranchMap is a map of source branch names in Upstream (keys) to use to update a corresponding
	// branch in Target (values), where Target is either a fork repo of Upstream or contains a
	// submodule of Upstream. The key is glob matched. If the value contains "?" (not a valid branch
	// character), "?" is replaced with the upstream branch name.
	BranchMap map[string]string

	// AutoSyncBranches is the list of branches that a call to "./cmd/sync" should bring up to date.
	// It should be a list of keys that match up with BranchMap entries. The "./cmd/releasego sync"
	// command ignores this list, syncing a user-specified branch instead that may not even be in
	// the AutoSyncBranches list.
	AutoSyncBranches []string

	// AutoMirrorBranches is a list of branches that should be mirrored to MirrorTarget, in addition
	// to the list of branches in AutoSyncBranches. A "*" is glob matched. "./cmd/releasego sync"
	// ignores this list to keep release activity separate from unrelated branch mirroring.
	AutoMirrorBranches []string

	// MainBranch is the main/master branch of the target repository. When creating a new release
	// branch, it is forked from the tip of this branch.
	MainBranch string

	// SourceBranchLatestCommit is a map of source branch names in Upstream (keys) and a full commit
	// hash to treat as the latest commit for that source branch, no matter what the upstream
	// repository says at the time of merge. This map can be used to avoid a race between the sync
	// infrastructure and upstream merge flow.
	SourceBranchLatestCommit map[string]string

	// AutoResolveTarget lists files and dirs that Upstream may have modified, but we want to keep
	// the contents as they are in Target. Normally files that are modified in our fork repos are
	// all in the 'eng/' directory to avoid merge conflicts (and keep the repository tidy), but in
	// some cases this isn't possible. In these cases, Target has in-place modifications that must
	// be auto-resolved during the sync process.
	AutoResolveTarget []string
	// SubmoduleTarget is the path of a submodule in the Target repo to update with the latest
	// version of Upstream and UpstreamMirror (if specified). If this option is not specified
	// (default), that indicates the entire Upstream repository should be merged into the Target
	// repository.
	SubmoduleTarget string

	// GoVersionFileContent	is empty, or the Go version that the microsoft/go build should use
	// after the sync. Should be in the upstream format, e.g. go1.17.10 and go1.18. Sync examines
	// VERSION in the submodule, and if it doesn't match the expected value, creates/updates VERSION
	// in the outer repo (microsoft/go) to specify it. Otherwise, cleans up the outer VERSION file.
	GoVersionFileContent string

	// GoMicrosoftRevisionFileContent is empty, or the Microsoft revision (1, 2, ...) that the
	// microsoft/go build should use after the sync. If 1, removes the MICROSOFT_REVISION file if
	// one exists. If 2 or more, creates a MICROSOFT_REVISION file to specify it.
	GoMicrosoftRevisionFileContent string
}

ConfigEntry is one entry in a sync config file. The file contains a JSON list of objects that match this struct.

func (*ConfigEntry) PRBranchStorageRepo

func (c *ConfigEntry) PRBranchStorageRepo() string

PRBranchStorageRepo returns the repo to store the PR branch on.

func (*ConfigEntry) TargetBranch

func (c *ConfigEntry) TargetBranch(upstream string) (string, error)

TargetBranch takes an upstream branch and returns the corresponding target branch. Returns an error if multiple target branches are found. Returns an empty string if no matches found.

type Flags

type Flags struct {
	DryRun          *bool
	InitialCloneDir *string

	GitHubUser        *string
	GitHubPAT         *string
	GitHubPATReviewer *string

	AzDODncengPAT *string

	SyncConfig *string
	TempGitDir *string

	CreateBranches *bool

	GitAuthString *string
}

func BindFlags

func BindFlags(workingDirectory string) *Flags

func (*Flags) MakeGitWorkDir

func (f *Flags) MakeGitWorkDir() (string, error)

func (*Flags) ParseAuth

func (f *Flags) ParseAuth() (gitcmd.URLAuther, error)

func (*Flags) ReadConfig

func (f *Flags) ReadConfig() ([]ConfigEntry, error)

type GitAuthOption

type GitAuthOption string

GitAuthOption contains a string value given on the command line to indicate what type of auth to use with GitHub URLs.

const (
	GitAuthNone GitAuthOption = "none"
	GitAuthSSH  GitAuthOption = "ssh"
	GitAuthPAT  GitAuthOption = "pat"
)

String values given on the command line. See usage help for details.

type SyncResult

type SyncResult struct {
	// PR is the GitHub PR creation response if a PR is necessary. If the target repo is already up
	// to date, this is nil. If this is the result of a dry run, PR may be nil even if a PR is
	// necessary, because a PR wasn't created.
	PR *gitpr.GitHubResponse
	// Commit is the commit hash that contains the updated result. This is either the commit that
	// was pushed for the PR, or a commit that already exists in the target repo.
	Commit string
}

SyncResult is the result of a sync call.

func MakeBranchPRs

func MakeBranchPRs(f *Flags, dir string, entry *ConfigEntry) ([]SyncResult, error)

MakeBranchPRs creates sync changes for each branch in the given entry and submits them as PRs. Multiple branches are processed at the same time in order to efficiently use Git: it is better to tell Git to fetch/push multiple branches at the same time than run the operations individually. Returns an error, or the sync results of each branch.