Examples with DocDefault com.google.copybara.doc.annotations.DocDefault used on opensource projects

Example 6 with DocDefault

use of com.google.copybara.doc.annotations.DocDefault in project copybara by google.

the class Core method todoReplace.

@SuppressWarnings("unused")
@StarlarkMethod(name = "todo_replace", doc = "Replace Google style TODOs. For example `TODO(username, othername)`.", parameters = { @Param(name = "tags", named = true, allowedTypes = { @ParamType(type = net.starlark.java.eval.Sequence.class, generic1 = String.class) }, doc = "Prefix tag to look for", defaultValue = "['TODO', 'NOTE']"), @Param(name = "mapping", named = true, doc = "Mapping of users/strings", defaultValue = "{}"), @Param(name = "mode", named = true, doc = "Mode for the replace:<ul><li>'MAP_OR_FAIL': Try to use the mapping and if not" + " found fail.</li><li>'MAP_OR_IGNORE': Try to use the mapping but ignore if" + " no mapping found.</li><li>'MAP_OR_DEFAULT': Try to use the mapping and use" + " the default if not found.</li><li>'SCRUB_NAMES': Scrub all names from" + " TODOs. Transforms 'TODO(foo)' to 'TODO'</li><li>'USE_DEFAULT': Replace any" + " TODO(foo, bar) with TODO(default_string)</li></ul>", defaultValue = "'MAP_OR_IGNORE'"), @Param(name = "paths", named = true, allowedTypes = { @ParamType(type = Glob.class), @ParamType(type = NoneType.class) }, doc = "A glob expression relative to the workdir representing the files to apply the" + " transformation. For example, glob([\"**.java\"]), matches all java files" + " recursively. Defaults to match all the files recursively.", defaultValue = "None"), @Param(name = "default", named = true, allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, doc = "Default value if mapping not found. Only valid for 'MAP_OR_DEFAULT' or" + " 'USE_DEFAULT' modes", defaultValue = "None"), @Param(name = "ignore", named = true, allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, doc = "If set, elements within TODO (with usernames) that match the regex will be " + "ignored. For example ignore = \"foo\" would ignore \"foo\" in " + "\"TODO(foo,bar)\" but not \"bar\".", defaultValue = "None") }, useStarlarkThread = true)
@DocDefault(field = "paths", value = "glob([\"**\"])")
@Example(title = "Simple update", before = "Replace TODOs and NOTES for users in the mapping:", code = "core.todo_replace(\n" + "  mapping = {\n" + "    'test1' : 'external1',\n" + "    'test2' : 'external2'\n" + "  }\n" + ")", after = "Would replace texts like TODO(test1) or NOTE(test1, test2) with TODO(external1)" + " or NOTE(external1, external2)")
@Example(title = "Scrubbing", before = "Remove text from inside TODOs", code = "core.todo_replace(\n" + "  mode = 'SCRUB_NAMES'\n" + ")", after = "Would replace texts like TODO(test1): foo or NOTE(test1, test2):foo with TODO:foo" + " and NOTE:foo")
@Example(title = "Ignoring Regex Patterns", before = "Ignore regEx inside TODOs when scrubbing/mapping", code = "core.todo_replace(\n" + "  mapping = { 'aaa' : 'foo'},\n" + "  ignore = 'b/.*'\n)", after = "Would replace texts like TODO(b/123, aaa) with TODO(b/123, foo)")
public TodoReplace todoReplace(// <String>
net.starlark.java.eval.Sequence<?> skyTags, // <String, String>
Dict<?, ?> skyMapping, String modeStr, Object paths, Object skyDefault, Object regexToIgnore, StarlarkThread thread) throws EvalException {
    Mode mode = stringToEnum("mode", modeStr, Mode.class);
    Map<String, String> mapping = SkylarkUtil.convertStringMap(skyMapping, "mapping");
    String defaultString = convertFromNoneable(skyDefault, /*defaultValue=*/
    null);
    ImmutableList<String> tags = ImmutableList.copyOf(SkylarkUtil.convertStringList(skyTags, "tags"));
    String ignorePattern = convertFromNoneable(regexToIgnore, null);
    Pattern regexIgnorelist = ignorePattern != null ? Pattern.compile(ignorePattern) : null;
    check(!tags.isEmpty(), "'tags' cannot be empty");
    if (mode == Mode.MAP_OR_DEFAULT || mode == Mode.USE_DEFAULT) {
        check(defaultString != null, "'default' needs to be set for mode '%s'", mode);
    } else {
        check(defaultString == null, "'default' cannot be used for mode '%s'", mode);
    }
    if (mode == Mode.USE_DEFAULT || mode == Mode.SCRUB_NAMES) {
        check(mapping.isEmpty(), "'mapping' cannot be used with mode %s", mode);
    }
    return new TodoReplace(thread.getCallerLocation(), convertFromNoneable(paths, Glob.ALL_FILES), tags, mode, mapping, defaultString, workflowOptions.parallelizer(), regexIgnorelist);
}

Example 7 with DocDefault

use of com.google.copybara.doc.annotations.DocDefault in project copybara by google.

the class Core method transform.

@SuppressWarnings("unused")
@StarlarkMethod(name = "transform", doc = "Groups some transformations in a transformation that can contain a particular," + " manually-specified, reversal, where the forward version and reversed version" + " of the transform are represented as lists of transforms. The is useful if a" + " transformation does not automatically reverse, or if the automatic reversal" + " does not work for some reason." + "<br>" + "If reversal is not provided, the transform will try to compute the reverse of" + " the transformations list.", parameters = { @Param(name = "transformations", allowedTypes = { @ParamType(type = net.starlark.java.eval.Sequence.class, generic1 = Transformation.class) }, named = true, doc = "The list of transformations to run as a result of running this transformation."), @Param(name = "reversal", allowedTypes = { @ParamType(type = net.starlark.java.eval.Sequence.class, generic1 = Transformation.class), @ParamType(type = NoneType.class) }, doc = "The list of transformations to run as a result of running this" + " transformation in reverse.", named = true, positional = false, defaultValue = "None"), @Param(name = "ignore_noop", allowedTypes = { @ParamType(type = Boolean.class), @ParamType(type = NoneType.class) }, doc = "WARNING: Deprecated. Use `noop_behavior` instead.\nIn case a noop error happens in" + " the group of transformations (Both forward and reverse), it will be" + " ignored, but the rest of the transformations in the group will still be" + " executed. If ignore_noop is not set, we will apply the closest parent's" + " ignore_noop.", named = true, positional = false, defaultValue = "None"), @Param(name = "noop_behavior", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, doc = "How to handle no-op transformations:<br><ul> <li><b>'IGNORE_NOOP'</b>: Any no-ops" + " among the wrapped transformations are ignored.</li>" + " <li><b>'NOOP_IF_ANY_NOOP'</b>: Throws an exception as soon as a single" + " wrapped transformation is a no-op.</li> <li><b>'NOOP_IF_ALL_NOOP'</b>:" + " Ignores no-ops from the wrapped transformations unless they all no-op, in" + " which case an exception is thrown.</li></ul>", named = true, positional = false, defaultValue = "None") })
@DocDefault(field = "reversal", value = "The reverse of 'transformations'")
@DocDefault(field = "noop_behavior", value = "NOOP_IF_ANY_NOOP")
public Transformation transform(// <Transformation>
net.starlark.java.eval.Sequence<?> transformations, Object reversal, Object ignoreNoop, Object noopBehaviorString) throws EvalException, ValidationException {
    checkCondition(Starlark.isNullOrNone(ignoreNoop) || Starlark.isNullOrNone(noopBehaviorString), "The deprecated param 'ignore_noop' cannot be set simultaneously with 'noop_behavior'." + " Prefer using 'noop_behavior'.");
    Sequence.NoopBehavior noopBehavior = stringToEnum("noop_behavior", convertFromNoneable(noopBehaviorString, "NOOP_IF_ANY_NOOP"), Sequence.NoopBehavior.class);
    if (Boolean.TRUE.equals(ignoreNoop)) {
        noopBehavior = Sequence.NoopBehavior.IGNORE_NOOP;
    } else if (Boolean.FALSE.equals(ignoreNoop)) {
        noopBehavior = Sequence.NoopBehavior.FAIL_IF_ANY_NOOP;
    }
    Sequence forward = Sequence.fromConfig(generalOptions.profiler(), workflowOptions, transformations, "transformations", printHandler, debugOptions::transformWrapper, noopBehavior);
    net.starlark.java.eval.Sequence<Transformation> reverseList = convertFromNoneable(reversal, null);
    if (reverseList == null) {
        try {
            reverseList = StarlarkList.immutableCopyOf(ImmutableList.of(forward.reverse()));
        } catch (NonReversibleValidationException e) {
            throw Starlark.errorf("transformations are not automatically reversible." + " Use 'reversal' field to explicitly configure the reversal of the transform");
        }
    }
    Sequence reverse = Sequence.fromConfig(generalOptions.profiler(), workflowOptions, reverseList, "reversal", printHandler, debugOptions::transformWrapper, noopBehavior);
    return new ExplicitReversal(forward, reverse);
}

Example 8 with DocDefault

use of com.google.copybara.doc.annotations.DocDefault in project copybara by google.

the class GitModule method gitHubDestination.

@SuppressWarnings("unused")
@StarlarkMethod(name = "github_destination", doc = "Creates a commit in a GitHub repository branch (for example master). For creating Pull" + "Request use git.github_pr_destination.", parameters = { @Param(name = "url", named = true, doc = "Indicates the URL to push to as well as the URL from which to get the parent " + "commit"), @Param(name = "push", named = true, doc = "Reference to use for pushing the change, for example 'main'.", defaultValue = "'master'"), @Param(name = "fetch", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, named = true, doc = "Indicates the ref from which to get the parent commit. Defaults to push value" + " if None", defaultValue = "None"), @Param(name = "pr_branch_to_update", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, named = true, doc = "A template string that refers to a pull request branch in the same repository" + " will be updated to current commit of this push branch only if" + " pr_branch_to_update exists. The reason behind this field is that" + " presubmiting changes creates and leaves a pull request open. By using" + " this, we can automerge/close this type of pull requests. As a result," + " users will see this pr_branch_to_update as merged to this push branch." + " Usage: Users can use a string or a string with a label. For instance" + " ${label}_pr_branch_name. And the value of label must be in changes' label" + " list. Otherwise, nothing will happen.", defaultValue = "None"), @Param(name = "partial_fetch", defaultValue = "False", named = true, doc = "This is an experimental feature that only works for certain origin globs."), @Param(name = "delete_pr_branch", allowedTypes = { @ParamType(type = Boolean.class), @ParamType(type = NoneType.class) }, named = true, doc = "When `pr_branch_to_update` is enabled, it will delete the branch reference" + " after the push to the branch and main branch (i.e master) happens. This" + " allows to cleanup temporary branches created for testing.", defaultValue = "None"), @Param(name = "integrates", named = true, allowedTypes = { @ParamType(type = Sequence.class, generic1 = GitIntegrateChanges.class), @ParamType(type = NoneType.class) }, defaultValue = "None", doc = "Integrate changes from a url present in the migrated change" + " label. Defaults to a semi-fake merge if COPYBARA_INTEGRATE_REVIEW label is" + " present in the message", positional = false), @Param(name = "api_checker", allowedTypes = { @ParamType(type = Checker.class), @ParamType(type = NoneType.class) }, defaultValue = "None", doc = "A checker for the Gerrit API endpoint provided for after_migration hooks. " + "This field is not required if the workflow hooks don't use the " + "origin/destination endpoints.", named = true, positional = false), @Param(name = "primary_branch_migration", allowedTypes = { @ParamType(type = Boolean.class) }, defaultValue = "False", named = true, positional = false, doc = "When enabled, copybara will ignore the 'push' and 'fetch' params if either is" + " 'master' or 'main' and instead try to establish the default git branch. If" + " this fails, it will fall back to the param's declared value.\n" + "This is intended to help migrating to the new standard of using 'main'" + " without breaking users relying on the legacy default."), @Param(name = "tag_name", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, named = true, positional = false, doc = "A template string that specifies to a tag name. If the tag already exists, " + "copybara will only overwrite it if the --git-tag-overwrite flag is set." + "\nNote that tag creation is " + "best-effort and the migration will succeed even if the tag cannot be " + "created. " + "Usage: Users can use a string or a string with a label. " + "For instance ${label}_tag_name. And the value of label must be " + "in changes' label list. Otherwise, tag won't be created.", defaultValue = "None"), @Param(name = "tag_msg", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, named = true, positional = false, doc = "A template string that refers to the commit msg for a tag. If set, copybara will" + "create an annotated tag with this custom message\n" + "Usage: Labels in the string will be resolved. E.g. .${label}_message." + "By default, the tag will be created with the labeled commit's message.", defaultValue = "None"), @Param(name = "checker", allowedTypes = { @ParamType(type = Checker.class), @ParamType(type = NoneType.class) }, defaultValue = "None", doc = "A checker that validates the commit files & message. If `api_checker` is not" + " set, it will also be used for checking API calls. If only `api_checker`" + "is used, that checker will only apply to API calls.", named = true, positional = false) }, useStarlarkThread = true)
@UsesFlags(GitDestinationOptions.class)
// Used to detect in the future users that don't set it and change the default
@DocDefault(field = "delete_pr_branch", value = "False")
public GitDestination gitHubDestination(String url, String push, Object fetch, Object prBranchToUpdate, Boolean partialFetch, Object deletePrBranchParam, Object integrates, Object apiChecker, Boolean primaryBranchMigration, Object tagName, Object tagMsg, Object checker, StarlarkThread thread) throws EvalException {
    GitDestinationOptions destinationOptions = options.get(GitDestinationOptions.class);
    String resolvedPush = checkNotEmpty(firstNotNull(destinationOptions.push, push), "push");
    GeneralOptions generalOptions = options.get(GeneralOptions.class);
    String repoUrl = fixHttp(checkNotEmpty(firstNotNull(destinationOptions.url, url), "url"), thread.getCallerLocation());
    String branchToUpdate = convertFromNoneable(prBranchToUpdate, null);
    Boolean deletePrBranch = convertFromNoneable(deletePrBranchParam, null);
    check(branchToUpdate != null || deletePrBranch == null, "'delete_pr_branch' can only be set if 'pr_branch_to_update' is used");
    GitHubOptions gitHubOptions = options.get(GitHubOptions.class);
    WorkflowOptions workflowOptions = options.get(WorkflowOptions.class);
    String effectivePrBranchToUpdate = branchToUpdate;
    if (options.get(WorkflowOptions.class).isInitHistory()) {
        generalOptions.console().infoFmt("Ignoring field 'pr_branch_to_update' as '--init-history' is set.");
        effectivePrBranchToUpdate = null;
    }
    // First flag has priority, then field, and then (for now) we set it to false.
    // TODO(malcon): Once this is stable the default will be 'branchToUpdate != null'
    boolean effectiveDeletePrBranch = gitHubOptions.gitHubDeletePrBranch != null ? gitHubOptions.gitHubDeletePrBranch : deletePrBranch != null ? deletePrBranch : false;
    Checker apiCheckerObj = convertFromNoneable(apiChecker, null);
    Checker checkerObj = convertFromNoneable(checker, null);
    return new GitDestination(repoUrl, checkNotEmpty(firstNotNull(destinationOptions.fetch, convertFromNoneable(fetch, null), resolvedPush), "fetch"), resolvedPush, partialFetch, primaryBranchMigration, convertFromNoneable(tagName, null), convertFromNoneable(tagMsg, null), destinationOptions, options.get(GitOptions.class), generalOptions, new GitHubWriteHook(generalOptions, repoUrl, gitHubOptions, effectivePrBranchToUpdate, effectiveDeletePrBranch, getGeneralConsole(), apiCheckerObj != null ? apiCheckerObj : checkerObj, GITHUB_COM), Starlark.isNullOrNone(integrates) ? defaultGitIntegrate : Sequence.cast(integrates, GitIntegrateChanges.class, "integrates"), checkerObj);
}

Example 9 with DocDefault

use of com.google.copybara.doc.annotations.DocDefault in project copybara by google.

the class GitModule method gerritDestination.

@SuppressWarnings("unused")
@StarlarkMethod(name = "gerrit_destination", doc = "Creates a change in Gerrit using the transformed worktree. If this is used in iterative" + " mode, then each commit pushed in a single Copybara invocation will have the" + " correct commit parent. The reviews generated can then be easily done in the" + " correct order without rebasing.", parameters = { @Param(name = "url", named = true, doc = "Indicates the URL to push to as well as the URL from which to get the parent " + "commit"), @Param(name = "fetch", named = true, doc = "Indicates the ref from which to get the parent commit"), @Param(name = "push_to_refs_for", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, defaultValue = "None", named = true, doc = "Review branch to push the change to, for example setting this to 'feature_x'" + " causes the destination to push to 'refs/for/feature_x'. It defaults to " + "'fetch' value."), @Param(name = "submit", named = true, doc = "If true, skip the push thru Gerrit refs/for/branch and directly push to branch." + " This is effectively a git.destination that sets a Change-Id", defaultValue = "False"), @Param(name = "partial_fetch", defaultValue = "False", named = true, doc = "This is an experimental feature that only works for certain origin globs."), @Param(name = "notify", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, named = true, doc = "" + "Type of Gerrit notify option (https://gerrit-review.googlesource.com/Docum" + "entation/user-upload.html#notify). Sends notifications by default.", defaultValue = "None"), @Param(name = "change_id_policy", defaultValue = "'FAIL_IF_PRESENT'", named = true, doc = "What to do in the presence or absent of Change-Id in message:" + "<ul>" + "  <li>`'REQUIRE'`: Require that the change_id is present in the message as a" + " valid label</li>" + "  <li>`'FAIL_IF_PRESENT'`: Fail if found in message</li>" + "  <li>`'REUSE'`: Reuse if present. Otherwise generate a new one</li>" + "  <li>`'REPLACE'`: Replace with a new one if found</li>" + "</ul>"), @Param(name = "allow_empty_diff_patchset", named = true, doc = "By default Copybara will upload a new PatchSet to Gerrit without checking the" + " previous one. If this set to false, Copybara will download current PatchSet" + " and check the diff against the new diff.", defaultValue = "True"), @Param(name = "reviewers", named = true, defaultValue = "[]", doc = "The list of the reviewers will be added to gerrit change reviewer listThe element" + " in the list is: an email, for example: \"foo@example.com\" or label for" + " example: ${SOME_GERRIT_REVIEWER}. These are under the condition of" + " assuming that users have registered to gerrit repos"), @Param(name = "cc", named = true, defaultValue = "[]", doc = "The list of the email addresses or users that will be CCed in the review. Can" + " use labels as the `reviewers` field."), @Param(name = "labels", named = true, defaultValue = "[]", doc = "The list of labels to be pushed with the change. The format is the label " + "along with the associated value. For example: Run-Presubmit+1"), @Param(name = "api_checker", allowedTypes = { @ParamType(type = Checker.class), @ParamType(type = NoneType.class) }, defaultValue = "None", doc = "A checker for the Gerrit API endpoint provided for after_migration hooks. " + "This field is not required if the workflow hooks don't use the " + "origin/destination endpoints.", named = true, positional = false), @Param(name = "integrates", allowedTypes = { @ParamType(type = Sequence.class, generic1 = GitIntegrateChanges.class), @ParamType(type = NoneType.class) }, named = true, defaultValue = "None", doc = "Integrate changes from a url present in the migrated change" + " label. Defaults to a semi-fake merge if COPYBARA_INTEGRATE_REVIEW label is" + " present in the message", positional = false), @Param(name = "topic", allowedTypes = { @ParamType(type = String.class), @ParamType(type = NoneType.class) }, defaultValue = "None", named = true, positional = false, doc = "" + "Sets the topic of the Gerrit change created.<br><br>" + "By default it sets no topic. This field accepts a template with labels. " + "For example: `\"topic_${CONTEXT_REFERENCE}\"`"), @Param(name = "gerrit_submit", defaultValue = "False", named = true, positional = false, doc = "By default, Copybara uses git commit/push to the main branch when submit = True." + "  If this flag is enabled, it will update the Gerrit change with the " + "latest commit and submit using Gerrit."), @Param(name = "primary_branch_migration", allowedTypes = { @ParamType(type = Boolean.class) }, defaultValue = "False", named = true, positional = false, doc = "When enabled, copybara will ignore the 'push_to_refs_for' and 'fetch' params if" + " either is 'master' or 'main' and instead try to establish the default git" + " branch. If this fails, it will fall back to the param's declared value.\n" + "This is intended to help migrating to the new standard of using 'main'" + " without breaking users relying on the legacy default."), @Param(name = "checker", allowedTypes = { @ParamType(type = Checker.class), @ParamType(type = NoneType.class) }, defaultValue = "None", doc = "A checker that validates the commit files & message. If `api_checker` is not" + " set, it will also be used for checking API calls. If only `api_checker`" + "is used, that checker will only apply to API calls.", named = true, positional = false) }, useStarlarkThread = true)
@UsesFlags(GitDestinationOptions.class)
@DocDefault(field = "push_to_refs_for", value = "fetch value")
public GerritDestination gerritDestination(String url, String fetch, Object pushToRefsFor, Boolean submit, Boolean partialFetch, Object notifyOptionObj, String changeIdPolicy, Boolean allowEmptyPatchSet, // <String>
Sequence<?> reviewers, // <String>
Sequence<?> ccParam, // <String>
Sequence<?> labelsParam, Object apiChecker, Object integrates, Object topicObj, Boolean gerritSubmit, Boolean primaryBranchMigrationMode, Object checker, StarlarkThread thread) throws EvalException {
    checkNotEmpty(url, "url");
    if (gerritSubmit) {
        Preconditions.checkArgument(submit, "Only set gerrit_submit if submit is true");
    }
    List<String> newReviewers = SkylarkUtil.convertStringList(reviewers, "reviewers");
    List<String> cc = SkylarkUtil.convertStringList(ccParam, "cc");
    List<String> labels = SkylarkUtil.convertStringList(labelsParam, "labels");
    String notifyOptionStr = convertFromNoneable(notifyOptionObj, null);
    check(!(submit && notifyOptionStr != null), "Cannot set 'notify' with 'submit = True' in git.gerrit_destination().");
    String topicStr = convertFromNoneable(topicObj, null);
    check(!(submit && topicStr != null), "Cannot set 'topic' with 'submit = True' in git.gerrit_destination().");
    NotifyOption notifyOption = notifyOptionStr == null ? null : stringToEnum("notify", notifyOptionStr, NotifyOption.class);
    Checker apiCheckerObj = convertFromNoneable(apiChecker, null);
    Checker checkerObj = convertFromNoneable(checker, null);
    return GerritDestination.newGerritDestination(options, fixHttp(url, thread.getCallerLocation()), checkNotEmpty(firstNotNull(options.get(GitDestinationOptions.class).fetch, fetch), "fetch"), checkNotEmpty(firstNotNull(convertFromNoneable(pushToRefsFor, null), options.get(GitDestinationOptions.class).fetch, fetch), "push_to_refs_for"), submit, partialFetch, notifyOption, stringToEnum("change_id_policy", changeIdPolicy, ChangeIdPolicy.class), allowEmptyPatchSet, newReviewers, cc, labels, apiCheckerObj != null ? apiCheckerObj : checkerObj, Starlark.isNullOrNone(integrates) ? defaultGitIntegrate : Sequence.cast(integrates, GitIntegrateChanges.class, "integrates"), topicStr, gerritSubmit, primaryBranchMigrationMode, checkerObj);
}