# Teams

> Group people into teams that own work, attach them to the projects they work in, file and filter tickets by team, and see how By Dawn's teams compare with Linear's.

This page helps you set up teams so everyone can see whose work each ticket is. By the end you'll have a team with
members and a lead, attached to the projects it works in, owning its tickets.

A team is a named group of people in your organization, such as everyone who owns the mobile apps. A team owns
work: each ticket can have one owning team, and the team has its own page with its work across every project.
A team can also be given access to a project or a Docs space, and everyone on it gets that access. Changing who's
on the team changes who has it.

Teams live in **Settings › Organization › Teams**. Everyone in the organization can see the teams and
who's on them.

## Teams and projects

By Dawn has two ways to group work, and they do different jobs:

- **A project is where work lives.** It gives each ticket its identifier (such as `MOB-88`), its board and columns,
  its cycles and estimates, its releases and its repos.
- **A team is who does the work.** It owns tickets, works in one or more projects, and has its own members, lead
  and page.

They're separate so that several teams can share one project, with one board and one set of repos, and one team can
work across several projects. A ticket's identifier never changes when it moves to another team, because the
identifier is also in its branch names and pull requests. So moving a ticket to another team changes only its team:
its identifier, column, cycle and labels stay as they are.

A project lists the teams that work in it, and one of them can be its **default team**. A ticket can only be owned
by a team that works in its project.

## Who can change a team

| You are | You can |
| --- | --- |
| An organization owner or admin | Create and archive teams, and edit any team and who's on it |
| A team's **Lead** | Rename that team, edit its profile and change who's on it, including making other leads |
| Anyone in the organization | See the teams and their members, and join or leave any open team |

The page says so for people who can't create teams: "Only owners and admins can create and archive teams. A team's
leads can edit it and manage its members. Join any open team yourself."

## Create a team

1. Type the team's name in **New team name, e.g. Platform**, and choose **Create team**. Names are 1 to 100
   characters, and no two teams can share one.

2. Choose **Details** next to the new team. It opens on the **Profile** tab, so you can give the team a key and the
   rest of its profile (see the next section).

3. Open the **Members** tab. Under **Add a person…**, pick someone from the organization, pick **Member** or
   **Lead**, and choose **Add**. Repeat for each person. "A lead can rename the team and manage who is on it."

Each team in the list shows how many members it has, and **You lead** or **You're on it** if you're on it yourself.
An invite-only team is marked **Invite only**.

## Set up the team's profile

The **Profile** tab holds what people see of the team around By Dawn. The team's leads and the organization's owners
and admins can change it, then choose **Save profile**.

| Field | What it's for |
| --- | --- |
| **Key** | "2–5 letters, unique in the organization. It labels the team on chips and filters; ticket ids keep their project prefix." Once a team has a key it can be changed but not removed. |
| **Icon** and **Colour** | How the team looks on chips, the sidebar and its page. |
| **Description** | "What the team works on." |
| **Time zone** | "Where the team works. With none, it keeps the organization's." |
| **Who can join** | **Open**: "Anyone in the organization can join and leave this team themselves." **Invite only**: "Only an admin or one of the team's leads can add people." |
| **Agent briefing** | "What a worker reads when this team owns its ticket: the team's conventions, where its code lives, who to ask." Up to 8,000 characters. |

## Join or leave a team

Choose **Join** next to an open team to put yourself on it, or **Leave** to take yourself off. Both happen at once.
Leaving an invite-only team asks first, because "you can't rejoin it yourself. One of its leads or an admin would
have to add you back."

A team marked **Managed by your identity provider** has no **Join** or **Leave**, because "A group in your
identity provider decides who is on this team." The organization's owner sets that up with a
[group mapping](https://docs.bydawn.com/scim/#map-groups-to-roles).

When you invite someone to the organization, you can pick the teams they'll join next to their email (see
[Members and invites](https://docs.bydawn.com/members/)). The invite then shows **Joins** and the teams.

## Attach a team to a project

A team has to work in a project before it can own the project's tickets. Open the project, then
**Settings › This project › Teams**. Project admins and the organization's owners and admins can
change it.

1. Under **Attach a team…**, pick the team.

2. Leave **Make it the default** on to make it the project's default team. It starts on when the project has no
   default yet.

3. Choose **Attach**.

Each attached team has **Make default** (or **Clear default** on the default team) and **Detach**. Detaching a team
keeps it on the tickets it already owns, but it's no longer offered for the project's tickets.

Attaching a team doesn't let anyone open the project. "Attaching a team doesn't give anyone access — that's
Members & access." To give a team access to a restricted project, see
[Project members and access](https://docs.bydawn.com/project-access/#give-a-team-access).

A team's own **Projects** tab, in **Settings › Organization › Teams**, lists the projects it works in.
Its **Project teams** button opens each one's settings.

## Own tickets by team

Once a team is attached to a project, the project's tickets can be owned by it:

- **New tickets.** "A new ticket goes to its creator's team when that team is here, otherwise to the default
  team." If you're on several of the project's teams, it's the first by name. The **Team** button in the composer
  shows which team it will be, and you can pick another or **No team**.
- **Change a ticket's team** with the team button in the ticket's header. Only the team changes.
- **On the board**, each card shows its team's key. The **Team** filter has **My teams**, each team and **No
  team**, and you can group the board by **Team**. The **My teams' tickets** view, under **For you**, shows
  "Tickets owned by a team you are on".
- **Share a saved view with a team.** When you save a view, pick **A team** under **Who sees it**. It's "Shown to the
  team's members, as they join and leave it."

None of these appear in a project that no team works in.

## Your teams and the team page

The sidebar's **Your teams** lists the teams you're on, each with **Active**, **Backlog** and **Epics**. Choosing a
team opens its page, with the team's work across every project you can open:

- **Overview**: what on the team's tickets needs you, which workers are running, and what the team recently shipped.
- **Active** and **Backlog**: the team's tickets in progress and planned, and those still in the backlog.
- **Epics**: the epics the team **Leads**, and those it **Contributes** to because it owns some of their tickets.
- **Members**: who's on the team. Its leads and the organization's admins can change it here too.
- **Docs**: the Docs spaces the team **Owns**, or has been **Granted**.

Tickets in a restricted project you can't open stay hidden from the team page, as they do everywhere else.

## Other places a team works

- **Project access.** Give a whole team a role on a project (see
  [Project members and access](https://docs.bydawn.com/project-access/#give-a-team-access)).
- **Docs.** Give a team access to a Docs space, or make it the space's owning team (see [Docs](https://docs.bydawn.com/docs-wiki/)).
- **Triage.** A project's triage rotation can take turns through **A team**: "Its members take turns in the order
  they joined the team."
- **Mentions.** Type `@` and the team's key or name in a comment to mention the whole team.
- **Chat.** A bound channel can have a **Default team** for the tickets it files, and a channel's subscription can
  be narrowed to some teams (see [Bind a channel](https://docs.bydawn.com/chat-channels/)).
- **Agents.** The team's **Agent briefing** is what a worker reads when the team owns its ticket.
- **Import.** When you bring work in from Linear, you choose **Which team owns the tickets** from each Linear team
  (see [Import from Linear](https://docs.bydawn.com/import-linear/)).

## Archive a team

There's no deleting a team, but an owner or admin can archive one. Choose **Archive**, then **Archive team**. By Dawn
tells you: "Its members stay in the organization, but lose any Docs access the team gave them, and spaces it owns
no longer have an owning team. Its name becomes free for a new team."

Archiving also takes the team off every ticket it owned and every project it worked in, and takes away any project
access the team gave its members. An archived team no longer appears in the list, and can't be brought back. Places
that still name it show **Archived team**.

## How By Dawn's teams compare with Linear's

If you're coming from Linear, most of a Linear team maps onto a By Dawn team, and its workflow maps onto the project:

| In Linear | In By Dawn |
| --- | --- |
| Every issue belongs to one team | A ticket has one owning team, or none |
| The team key is the issue ID prefix (`ENG-123`) | The project's prefix is the ID (`MOB-88`). A team key labels chips and filters only |
| Moving an issue to another team changes its ID | Moving a ticket to another team changes only its team |
| Each team has its own statuses, cycles and estimates | The project has them, and each team sees them through its filter |
| Projects can span teams, with a lead team | Teams are attached to projects, with a default team. An epic shows the team that leads it and the teams that contribute |
| Team members and owners | Members and **Lead**s |
| Join and leave, private teams | Join and leave open teams, invite-only teams. Use a restricted project with team access for private work |
| Team agent guidance | The team's **Agent briefing** |
| Triage responsibility | A triage rotation that takes turns through a team |
| SCIM-managed teams | An identity provider group mapped to a team |
| Team labels, templates and sub-teams | Not yet: labels and templates belong to the organization |

[Coming from Linear or Jira](https://docs.bydawn.com/learn/coming-from-linear-or-jira/) covers the rest of the move.

## FAQ

**Should I make a project or a team?**

Make a project for each set of repos and board you work on, and a team for each group of people who own work. A
company with one product often has one project and several teams in it.

**Does attaching a team to a project let its members open the project?**

No. Attaching says which teams own the project's tickets. To let a team open a restricted project, give it access in
[Project members and access](https://docs.bydawn.com/project-access/#give-a-team-access).

**Why does By Dawn say another team already uses that name?**

By Dawn compares team names without their case or punctuation, so `Platform` and `platform!` count as the same name. Pick
a different one, or archive the old team first. Each team's key has to be unique too.

**Can a ticket belong to two teams?**

No, a ticket has one owning team. An epic shows every team that owns some of its tickets as contributing.

## Where to go next

- [Project members and access](https://docs.bydawn.com/project-access/): who can open each project, including whole teams.
- [Members and invites](https://docs.bydawn.com/members/): bring people into the organization first.
- [Organize work by team](https://docs.bydawn.com/developers/organize-work-by-team/): teams in the API, for developers.

Source: https://docs.bydawn.com/teams/