Connect and set up

Projects, pickup and governance

How a project ties a tracker, repositories and engineers together, and what each kind of work may do.

A project connects one work tracker to one or more repositories (each with its stack) and to the engineers who work on it. You create projects on the Projects page.

Changing a project

Choose Edit on a project to rename it, change its kind of work or its tracker, change a repository's stack or base branch, add a repository, or remove one (a project keeps at least one). When a project lacks something, for example no engineers or a connection that needs a field, the list says Needs: …. Engineers, automatic pickup and production code keep their own buttons. Stories already started keep what they were given.

Governance per kind of work

Every project says, for each kind of work — tests, specifications and production code — whether Yavaren may do it, how many reviewers a pull request needs, and whether tests must be included. Work a project does not allow is refused before it starts.

Automatic pickup

With automatic pickup on, Yavaren looks at your tracker on a schedule (every 15 minutes unless you choose otherwise). It starts stories that a person approved and marked ready, and breaks features marked ready into proposed stories for you to review. Nothing is started twice: a story that failed is started again only when a person asks.

Webhooks

Instead of waiting for the schedule, your tracker can call Yavaren when a story changes. Create the webhook address on the project; the address contains a secret token, so treat it like a password and replace it if it leaks.

Yavaren's understanding of your code, in your tracker

When Yavaren breaks a feature into stories, it writes down how it understands your current code, for two audiences:

• On the feature, for business readers: a comment listing the proposed stories and the business functions of your current system the feature touches: what each does today and what the feature changes, without code words. Your feature's own description is never rewritten.
• On each story, for engineers: its technical design: the components, interfaces (APIs, screens, events), data and tests it changes, named from your code, with "new" for what does not exist yet. It is in the story's description, or in a comment on the story when it would make the description too long for your tracker.

When a feature needs more detail first, the comment on it and the refined draft also carry the business functions. It works the same on Azure DevOps, Jira, GitHub and GitLab.

The full analysis as a file. Yavaren also attaches its complete analysis, yavaren-analysis-<feature>.md, to the feature (and to a refined draft): the outcome, the current state of the code as it read it, every proposed story with its technical design and acceptance criteria. The comment names the file. On Azure DevOps it is under Attachments, on Jira in the issue's attachments, on GitLab a link in the comment. GitHub has no way to attach a file to an issue, so there the comments carry the analysis and the job's result keeps it.

A draft feature written for a business review. A refined draft starts with "Proposed by Yavaren for business review", then why a clearer version is proposed, the proposed description, the business functions it touches and a link to the original feature, with the acceptance criteria in your tracker's own field (Azure DevOps) or as a checklist. It is laid out in your tracker's format: rich text on Azure DevOps, wiki text on Jira, Markdown on GitHub and GitLab. Proposed stories' acceptance criteria are a list (a checklist on GitHub and GitLab).

"Needs more detail before it can be split into stories"

Before Yavaren breaks a feature into stories, it checks that the feature says enough to write stories from: what is in scope, the options or rules a person can choose, and how to tell it is done. When something critical is missing (for example, a "notification preferences" feature that names no notification types or channels), it does not guess. Instead it:

• proposes a clearer version as a new draft feature in your tracker, tagged proposed-feature, for the person who owns the requirement;
• tags the original feature feature-needs-refinement;
• adds a comment to the original feature saying why, with a link to the draft and the next steps (on Azure DevOps it also links the two under Related Work);
• creates no stories and changes no code. This is not a failure.

Next, the owner of the requirement adds the missing details: either to the original feature (then removes feature-needs-refinement and tags it feature-agent-ready again), or by approving the draft. Yavaren then proposes the stories for your approval. The job's Result column and its log say why, name the draft and these steps.

Steps in your tracker

Some steps happen in your own tracker, not in Yavaren. On the Projects page, Steps in your tracker shows them for each project, with the exact names that project uses:

• The two tags or labels a person adds: feature-agent-ready on a feature to have it split into stories, and your approval signal (approved unless you chose another tag or a state) on a proposed story or a refined draft feature. Every other tag (pending-review, agent-ready, proposed-feature, feature-needs-refinement, target:…, …) is added by Yavaren; never add agent-ready by hand.
• Whether anything has to be created first. Azure DevOps creates a tag the first time it is used, as long as the account may create tag definitions (the default for Contributors); if your organisation turned that off, an administrator adds each tag once. Jira, GitHub and GitLab create labels the first time they are used; on GitHub and GitLab you may create them first to choose their colours.
• Where to find what Yavaren proposed (for example an Azure DevOps query “Tags Contains proposed-feature”, a Jira filter labels = "proposed-feature"). On Azure DevOps a draft feature and proposed stories are created in the same area and iteration as their feature, so they show on that team's backlog.
• What your tracker must allow (work item types, the token's permissions).