func (r *release) EnsureClosable() error {
	// Prepare for API calls.
	_, owner, repo, err := r.prepareForApiCalls()
	if err != nil {
		return err
	}

	// Get the relevant review milestone.
	releaseString := r.v.BaseString()
	task := fmt.Sprintf("Get GitHub review milestone for release %v", releaseString)
	log.Run(task)
	milestone, err := milestoneForVersion(r.tool.config, owner, repo, r.v)
	if err != nil {
		return errs.NewError(task, err)
	}
	if milestone == nil {
		return errs.NewErrorWithHint(task, errors.New("milestone not found"),
			fmt.Sprintf("\nMake sure the review milestone for release %v exists\n\n", r.v))
	}

	// Close the milestone unless there are some issues open.
	task = fmt.Sprintf(
		"Make sure the review milestone for release %v can be closed", releaseString)
	if num := *milestone.OpenIssues; num != 0 {
		hint := fmt.Sprintf(
			"\nreview milestone for release %v cannot be closed: %v issue(s) open\n\n",
			releaseString, num)
		return errs.NewErrorWithHint(task, common.ErrNotClosable, hint)
	}
	r.closingMilestone = milestone
	return nil
}

func ensureRbtVersion() error {
	hint := `
You need to install RBTools version 0.7. Please run

  $ pip install rbtools==0.7 --allow-external rbtools --allow-unverified rbtools

to install the correct version.

`

	// Load configuration and check the RBTools version only if Review Board is being used.
	config, err := common.LoadConfig()
	if err != nil {
		return err
	}
	if config.CodeReviewToolId() != Id {
		return nil
	}

	// Check the RBTools version being used.
	task := "Check the RBTools version being used"
	log.Run(task)

	// rbt 0.5.x prints the version string to stdout,
	// rbt 0.6.x prints the version string to stderr.
	stdout, stderr, err := shell.Run("rbt", "--version")
	if err != nil {
		// Return the hint instead of stderr.
		// Failing to run rbt --version probably means that it's not installed.
		return errs.NewErrorWithHint(task, err, hint)
	}

	var outputBuffer *bytes.Buffer
	if stdout.Len() != 0 {
		outputBuffer = stdout
	} else {
		outputBuffer = stderr
	}
	output := outputBuffer.String()

	pattern := regexp.MustCompile("^RBTools (([0-9]+)[.]([0-9]+).*)")
	parts := pattern.FindStringSubmatch(output)
	if len(parts) != 4 {
		err := fmt.Errorf("failed to parse 'rbt --version' output: %v", output)
		return errs.NewError(task, err)
	}
	rbtVersion := parts[1]
	// No need to check errors, we know the format is correct.
	major, _ := strconv.Atoi(parts[2])
	minor, _ := strconv.Atoi(parts[3])

	if !(major == 0 && minor == 7) {
		return errs.NewErrorWithHint(
			task, errors.New("unsupported rbt version detected: "+rbtVersion), hint)
	}

	return nil
}

func readAndUnmarshalConfig(absolutePath string, v interface{}) error {
	currentBranch := func() string {
		branch, err := gitutil.CurrentBranch()
		if err != nil {
			return err.Error()
		}
		return branch
	}

	// Read the file.
	task := "Read given configuration file"
	content, err := ioutil.ReadFile(absolutePath)
	if err != nil {
		hint := fmt.Sprintf(`
Failed to read the configuration file expected to be located at

  %v

The Git branch where the error occurred: %v

Make sure the configuration file exists and is committed
at the Git branch mentioned above.

You might want to check 'repo bootstrap' command
to see how the given configuration file can be generated.

`, absolutePath, currentBranch())
		return errs.NewErrorWithHint(task, err, hint)
	}

	// Unmarshall the content.
	task = "Unmarshal given configuration file"
	if err := Unmarshal(content, v); err != nil {
		hint := fmt.Sprintf(`
Failed to parse the configuration file located at

  %v

The Git branch where the error occurred: %v

Make sure the configuration file is valid JSON
that follows the right configuration schema.

You might want to check 'repo bootstrap' command
to see how the given configuration file can be re-generated.

`, absolutePath, currentBranch())

		return errs.NewErrorWithHint(task, err, hint)
	}

	return nil
}

func GetCodeReviewTool() (common.CodeReviewTool, error) {
	// Load configuration.
	config, err := common.LoadConfig()
	if err != nil && config == nil {
		return nil, err
	}

	// Choose the code review tool based on the configuration.
	var task = "Instantiate the selected code review plugin"
	id := config.CodeReviewToolId()
	factory, ok := codeReviewToolFactories[id]
	if !ok {
		// Collect the available code review tool ids.
		ids := make([]string, 0, len(codeReviewToolFactories))
		for id := range codeReviewToolFactories {
			ids = append(ids, id)
		}

		hint := fmt.Sprintf("\nAvailable code review tools: %v\n\n", ids)
		return nil, errs.NewErrorWithHint(
			task, fmt.Errorf("unknown code review tool: '%v'", id), hint)
	}

	// Try to instantiate the code review tool.
	tool, err := factory()
	if err != nil {
		return nil, errs.NewError(task, err)
	}

	return tool, nil
}

func (release *runningRelease) EnsureStageable() error {
	task := "Make sure the stories can be staged"
	log.Run(task)

	// Load the assigned stories.
	stories, err := release.loadStories()
	if err != nil {
		return errs.NewError(task, err)
	}

	var details bytes.Buffer
	tw := tabwriter.NewWriter(&details, 0, 8, 4, '\t', 0)
	io.WriteString(tw, "\n")
	io.WriteString(tw, "Story URL\tError\n")
	io.WriteString(tw, "=========\t=====\n")

	// For a story to be stageable, it must be in the Finished stage.
	// That by definition means that it has been reviewed and verified.
	for _, story := range stories {
		if !stateAtLeast(story, pivotal.StoryStateFinished) {
			fmt.Fprintf(tw, "%v\t%v\n", story.URL, "story not finished yet")
			err = common.ErrNotStageable
		}
	}
	if err != nil {
		io.WriteString(tw, "\n")
		tw.Flush()
		return errs.NewErrorWithHint(task, err, details.String())
	}
	return nil
}

func runMain(versionString string) error {
	// Make sure the version string is correct.
	task := "Parse the command line VERSION argument"
	ver, err := version.Parse(versionString)
	if err != nil {
		hint := `
The version string must be in the form of Major.Minor.Patch
and no part of the version string can be omitted.

`
		return errs.NewErrorWithHint(task, err, hint)
	}

	// In case -commit is set, set and commit the version string.
	if flagCommit {
		currentBranch, err := gitutil.CurrentBranch()
		if err != nil {
			return err
		}

		_, err = version.SetForBranch(ver, currentBranch)
		return err
	}

	// Otherwise just set the version.
	return version.Set(ver)
}

func ensureStoryIdTag(commits []*git.Commit) error {
	task := "Make sure all commits contain the Story-Id tag"

	storyIdTag := flagStoryIdTag
	if storyIdTag != "" && storyIdTag != git.StoryIdUnassignedTagValue {
		if err := checkStoryIdTag(storyIdTag); err != nil {
			return errs.NewError(task, err)
		}
	}

	var (
		hint    = bytes.NewBufferString("\n")
		missing bool
	)
	for _, commit := range commits {
		if commit.StoryIdTag == "" {
			if storyIdTag != "" {
				commit.StoryIdTag = storyIdTag
				continue
			}

			fmt.Fprintf(hint, "Commit %v is missing the Story-Id tag\n", commit.SHA)
			missing = true
		}
	}
	fmt.Fprintf(hint, "\n")

	if missing {
		return errs.NewErrorWithHint(
			task, errors.New("Story-Id tag missing"), hint.String())
	}
	return nil
}

func GetIssueTracker() (common.IssueTracker, error) {
	// Load configuration.
	config, err := common.LoadConfig()
	if err != nil && config == nil {
		return nil, err
	}

	// Choose the issue tracker based on the configuration.
	var task = "Instantiate the selected issue tracker plugin"
	id := config.IssueTrackerId()
	factory, ok := issueTrackerFactories[id]
	if !ok {
		// Collect the available tracker ids.
		ids := make([]string, 0, len(issueTrackerFactories))
		for id := range issueTrackerFactories {
			ids = append(ids, id)
		}

		hint := fmt.Sprintf("\nAvailable issue trackers: %v\n\n", ids)
		return nil, errs.NewErrorWithHint(
			task, fmt.Errorf("unknown issue tracker: '%v'", id), hint)
	}

	// Try to instantiate the issue tracker.
	tracker, err := factory()
	if err != nil {
		return nil, errs.NewError(task, err)
	}

	return tracker, nil
}

func SetConfigString(key string, value string) error {
	task := fmt.Sprintf("Run 'git config %v %v'", key, value)
	_, stderr, err := shell.Run("git", "config", key, value)
	if err != nil {
		return errs.NewErrorWithHint(task, err, stderr.String())
	}
	return nil
}

func ensureCommitsPushed(commits []*git.Commit) error {
	task := "Make sure that all commits exist in the upstream repository"

	// Load git-related config.
	gitConfig, err := git.LoadConfig()
	if err != nil {
		return errs.NewError(task, err)
	}
	remoteName := gitConfig.RemoteName
	remotePrefix := remoteName + "/"

	// Check each commit one by one.
	//
	// We run `git branch -r --contains HASH` for each commit,
	// then we check the output. In case there is a branch prefixed
	// with the right upstream name, the commit is treated as pushed.
	var (
		hint    = bytes.NewBufferString("\n")
		missing bool
	)
CommitLoop:
	for _, commit := range commits {
		// Get `git branch -r --contains HASH` output.
		stdout, err := git.Run("branch", "-r", "--contains", commit.SHA)
		if err != nil {
			return errs.NewError(task, err)
		}

		// Parse `git branch` output line by line.
		scanner := bufio.NewScanner(stdout)
		for scanner.Scan() {
			line := scanner.Text()
			if strings.HasPrefix(strings.TrimSpace(line), remotePrefix) {
				// The commit is contained in a remote branch, continue.
				continue CommitLoop
			}
		}
		if err := scanner.Err(); err != nil {
			return errs.NewError(task, err)
		}

		// The commit is not contained in any remote branch, bummer.
		fmt.Fprintf(hint,
			"Commit %v has not been pushed into remote '%v' yet.\n", commit.SHA, remoteName)
		missing = true
	}
	fmt.Fprintf(hint, "\n")
	fmt.Fprintf(hint, "All selected commits need to be pushed into the upstream pository.\n")
	fmt.Fprintf(hint, "Please make sure that is the case before trying again.\n")
	fmt.Fprintf(hint, "\n")

	// Return an error in case there is any commit that is not pushed.
	if missing {
		return errs.NewErrorWithHint(
			task, fmt.Errorf("some commits not found in upstream '%v'", remoteName), hint.String())
	}
	return nil
}

func fetchOrUpdateSkeleton(skeleton string) error {
	// Parse the skeleton string.
	parts := strings.SplitN(skeleton, "/", 2)
	if len(parts) != 2 {
		return fmt.Errorf("not a valid repository path string: %v", skeleton)
	}
	owner, repo := parts[0], parts[1]

	// Create the cache directory if necessary.
	task := "Make sure the local cache directory exists"
	cacheDir, err := cacheDirectoryAbsolutePath()
	if err != nil {
		return errs.NewError(task, err)
	}
	if err := os.MkdirAll(cacheDir, 0755); err != nil {
		return errs.NewError(task, err)
	}

	// Pull or close the given skeleton.
	task = "Pull or clone the given skeleton"
	skeletonDir := filepath.Join(cacheDir, "github.com", owner)

	if err := os.MkdirAll(skeletonDir, 0755); err != nil {
		return errs.NewError(task, err)
	}

	skeletonPath := filepath.Join(skeletonDir, repo)
	if _, err := os.Stat(skeletonPath); err != nil {
		if !os.IsNotExist(err) {
			return errs.NewError(task, err)
		}

		// The directory does not exist, hence we clone.
		task := fmt.Sprintf("Clone skeleton '%v'", skeleton)
		log.Run(task)
		args := []string{
			"clone",
			"--single-branch",
			fmt.Sprintf("https://github.com/%v/%v", owner, repo),
			skeletonPath,
		}
		if _, err := git.Run(args...); err != nil {
			return errs.NewError(task, err)
		}
		return nil
	}

	// The skeleton directory exists, hence we pull.
	task = fmt.Sprintf("Pull skeleton '%v'", skeleton)
	log.Run(task)
	cmd, _, stderr := shell.Command("git", "pull")
	cmd.Dir = skeletonPath
	if err := cmd.Run(); err != nil {
		return errs.NewErrorWithHint(task, err, stderr.String())
	}
	return nil
}

func RunCommand(command string, args ...string) (stdout *bytes.Buffer, err error) {
	argsList := make([]string, 2, 2+len(args))
	argsList[0], argsList[1] = "--no-pager", command
	argsList = append(argsList, args...)

	task := fmt.Sprintf("Run 'git %v' with args = %#v", command, args)
	log.V(log.Debug).Log(task)
	stdout, stderr, err := shell.Run("git", argsList...)
	if err != nil {
		return nil, errs.NewErrorWithHint(task, err, stderr.String())
	}
	return stdout, nil
}

// RefExistsStrict requires the whole ref path to be specified,
// e.g. refs/remotes/origin/master.
func RefExistsStrict(ref string) (exists bool, err error) {
	task := fmt.Sprintf("Run 'git show-ref --quiet --verify %v'", ref)
	_, stderr, err := shell.Run("git", "show-ref", "--verify", "--quiet", ref)
	if err != nil {
		if stderr.Len() != 0 {
			// Non-empty error output means that there was an error.
			return false, errs.NewErrorWithHint(task, err, stderr.String())
		}
		// Otherwise the ref does not exist.
		return false, nil
	}
	// No error means that the ref exists.
	return true, nil
}

func loadActiveModule(kind loader.ModuleKind) (loader.Module, error) {
	// Load local configuration.
	localConfig, err := config.ReadLocalConfig()
	if err != nil {
		return nil, err
	}

	// Get the module matching the module kind.
	activeModuleId := loader.ActiveModule(localConfig, kind)
	if activeModuleId == "" {
		task := fmt.Sprintf("Get active module ID for module kind '%v'", kind)
		err := &ErrModuleNotSet{kind}
		hint := "\nMake sure the ID is specified in the local configuration file.\n\n"
		return nil, errs.NewErrorWithHint(task, err, hint)
	}

	// Find the module among the registered modules.
	for _, module := range registeredModules {
		if module.Id() == activeModuleId {
			return module, nil
		}
	}

	task := fmt.Sprintf("Load active module for module kind '%v'", kind)
	err = &ErrModuleNotFound{activeModuleId}
	hint := `
The module for the given module ID was not found.
This can happen for one of the following reasons:

  1. the module ID as stored in the local configuration file is mistyped, or
  2. the module for the given module ID was not linked into your SalsaFlow.

Check the scenarios as mentioned above to fix the issue.

`
	return nil, errs.NewErrorWithHint(task, err, hint)
}

func GetConfigString(key string) (value string, err error) {
	task := fmt.Sprintf("Run 'git config %v'", key)
	stdout, stderr, err := shell.Run("git", "config", key)
	if err != nil {
		if stderr.Len() == 0 {
			// git config returns exit code 1 when the key is not set.
			// This can be detected by stderr being of zero length.
			// We treat this as the key being set to "".
			return "", nil
		}
		// Otherwise there is an error.
		return "", errs.NewErrorWithHint(task, err, stderr.String())
	}
	// Just return what was printed to stdout.
	return strings.TrimSpace(stdout.String()), nil
}

// LoadConfig can be used to load SalsaFlow configuration
// according to the given configuration specification.
//
// The main difference between BootstrapConfig and LoadConfig is that
// LoadConfig returns an error when the local configuration is not valid.
// While `repo bootstrap` is using BootstrapConfig, all other modules
// and commands should be using LoadConfig. The local configuration file
// is only supposed to be generated once during `repo bootstrap`.
func LoadConfig(spec ConfigSpec) (err error) {
	if spec == nil {
		return errs.NewErrorWithHint(
			"Load configuration according to the specification",
			errors.New("nil configuration specification provided"),
			`
Nil configuration specification provided,
please contact the module author to have it fixed.

`,
		)
	}

	if err := bootstrapGlobalConfig(spec); err != nil {
		return err
	}
	return loadLocalConfig(spec)
}

func UnmarshalGlobalConfig(v interface{}) error {
	// Read the global config file into the cache in case it's not there yet.
	if globalContentCache == nil {
		globalContent, err := readGlobalConfig()
		if err != nil {
			return err
		}
		globalContentCache = globalContent.Bytes()
	}

	// Unmarshal the global config file.
	task := "Unmarshal the global configuration file"
	if err := yaml.Unmarshal(globalContentCache, v); err != nil {
		return errs.NewErrorWithHint(
			task, err, "Make sure the configuration file is valid YAML\n")
	}
	return nil
}

func ensureNoMergeCommits(commits []*git.Commit) error {
	var (
		task = "Make sure there are no merge commits"
		hint bytes.Buffer
		err  error
	)
	fmt.Fprintln(&hint)
	for _, commit := range commits {
		if commit.Merge != "" {
			fmt.Fprintf(&hint, "Commit %v is a merge commit\n", commit.SHA)
			err = errors.New("merge commit detected")
		}
	}
	fmt.Fprintln(&hint)
	if err != nil {
		return errs.NewErrorWithHint(task, err, hint.String())
	}
	return nil
}

func (release *runningRelease) EnsureClosable() error {
	versionString := release.version.BaseString()

	task := fmt.Sprintf(
		"Make sure that the stories associated with release %v can be released", versionString)
	log.Run(task)

	// Make sure the stories are loaded.
	stories, err := release.loadStories()
	if err != nil {
		return errs.NewError(task, err)
	}

	// Make sure all relevant stories are accepted.
	// This includes the stories with SkipCheckLabels.
	notAccepted := make([]*pivotal.Story, 0, len(stories))
	for _, story := range stories {
		if story.State != pivotal.StoryStateAccepted {
			notAccepted = append(notAccepted, story)
		}
	}

	// In case there is no story that is not accepted, we are done.
	if len(notAccepted) == 0 {
		return nil
	}

	// Generate the error hint.
	var hint bytes.Buffer
	tw := tabwriter.NewWriter(&hint, 0, 8, 2, '\t', 0)
	fmt.Fprintf(tw, "\nThe following stories cannot be released:\n\n")
	fmt.Fprintf(tw, "Story URL\tState\n")
	fmt.Fprintf(tw, "=========\t=====\n")
	for _, story := range notAccepted {
		fmt.Fprintf(tw, "%v\t%v\n", story.URL, story.State)
	}
	fmt.Fprintf(tw, "\n")
	tw.Flush()

	return errs.NewErrorWithHint(task, common.ErrNotClosable, hint.String())
}

func Run(scriptName string, args ...string) (stdout *bytes.Buffer, err error) {
	task := fmt.Sprintf("Run the %v script", scriptName)

	// Get the command for the given script name and args.
	cmd, err := Command(scriptName, args...)
	if err != nil {
		return nil, errs.NewError(task, err)
	}

	// Run the given script in the repository root.
	var (
		sout bytes.Buffer
		serr bytes.Buffer
	)
	cmd.Stdout = &sout
	cmd.Stderr = &serr
	if err := cmd.Run(); err != nil {
		return nil, errs.NewErrorWithHint(task, err, serr.String())
	}
	return &sout, nil
}