The backup of a project#

Download the backup on the tab Settings → Backup of a project saves a file of YAML with all that the people of the project decided: the project, its repositories, filters, steps with the skips of pull requests, message and roles; Restore reads such a file back, see Backup. Writers and owners of the project download backups; only the owners restore them, because a backup can replace filters and steps. The file starts with a comment that says what it is and links this page. A snapshot keeps the same file on dashboard.pycal.org, see Snapshots; downloaded, it restores as a backup.

# A backup of the project iCalendar of https://dashboard.pycal.org.
# The format, version 1: https://docs.dashboard.pycal.org/reference/backup.html
dashboard_backup: 1
documentation: https://docs.dashboard.pycal.org/reference/backup.html
exported: '2026-11-20T09:00:00+00:00'
site: https://dashboard.pycal.org
project:
  name: iCalendar
  slug: icalendar
  description: The calendar library of Python.
  public: true
  step_labels: sync
repositories:
- collective/icalendar
filters:
- name: Review
  description: Waiting for a review.
  columns:
  - labels~applies~present~needs review
  - status~all~open
steps:
- name: Review
  filter: Review
  summary: Thanks, {author_mention}!
  hidden: false
  color: '#bfdbfe'
  tasks:
    labels~applies~present~needs review:
      summary: Review it
      description: Ask in the chat.
  actions:
    enter:
      add: [needs review]
      remove: []
    complete:
      add: []
      remove: [needs review]
  skip_authors: [niccokunzmann]
  skips:
  - repository: collective/icalendar
    number: 2185
    by: niccokunzmann
    reason: Reviewed in the chat.
    created: '2026-11-19T10:00:00+00:00'
message:
  template: '{pr_badge} **{step_name}** {tasks_all}'
  draft: '{pr_badge} **{step_name}**'
  listed: ['2166']
  to_listed: true
  to_new: false
  to_open: true
  to_closed: false
members:
- handle: niccokunzmann
  role: owner

The keys#

dashboard_backup

The version of the format, a number: 1. A site restores only the versions it knows; a newer version comes with a new version of the site.

documentation

The address of this page.

exported, site

When and where the backup was made; restoring does not read them.

project

name and description (Markdown), step_labels (off or sync, see PR Sync), and slug and public, which restoring leaves as they are: the address and the visibility of the project.

repositories

The names of the repositories, such as collective/icalendar. Restoring adds those that the project lacks, as the tab Repositories does, with the rights of the person who restores: a private repository needs the GitHub App, and goes only into a private project.

filters

The saved filters, each with its name, unique in the file, its description and its columns: the columns of conditions as the address of the table keeps them, see Columns of conditions.

steps

The steps from left to right, each with its name, the name of its filter in the file, its summary, whether it is hidden in the page of a pull request, its color (such as #bfdbfe, or empty), the tasks (the summary and description of each condition of its filter, by the column) and its actions: the labels to add and to remove when a pull request will enter the step or complete it, and skip_authors, the GitHub handles of the authors whose pull requests skip it. Its skips are the pull requests that skip it because a person said so: the repository and number of the pull request, the GitHub handle of the person (by), the reason and when it was created.

message

The Status Message of the tab PR Sync, see PR Sync: its template, the edited message that is not applied yet (draft, empty when there is none), the pull requests listed by their numbers, and the switches of its scope, to_listed, to_new, to_open and to_closed; empty without a message. New pull requests count from the time of restoring.

members

The roles in the project: the GitHub handle of each person and the role, read, write or owner.

A backup keeps everything that the people of a project decide; tests/test_backup.py checks every field. Left out are the ids and times of the database, who made or changed something last, and what GitHub tells, which the next update reads again: the labels of the steps on GitHub, which step a pull request is in, and the comments of PR Sync.

Restoring#

Restoring compares the file with the project first and shows what it changes; nothing changes until Restore the backup on that page. Filters and steps are the same when their names are.

  • What only adds is restored: the filters and steps that the project lacks (new steps come last), the message when the project has none, the skips of pull requests that the project knows, and the repositories that it lacks, as the tab Repositories adds them.

  • What deletes or replaces something happens only when it is ticked, and nothing is ticked at first: a filter or a step that differs from the backup is replaced, one added after the backup is deleted (a filter with its step), the name, the description, the step labels and the message are replaced, and the steps are ordered as in the backup. A role is given only when it is ticked, too; a person who never signed in gets none.

When steps change, restoring forgets which step each open pull request was in: the next update only records it, so no label is added or removed because of the restored steps. A file that is not a backup, has another version, or has a wrong part, such as a step whose filter is not in the file, changes nothing: the page says what is wrong, see BackupInvalid and BackupVersionUnknown.

The backup of a project as a file of YAML: all that people decided about it.

Its settings, repositories, filters, steps with the skips of pull requests, message and roles. Restoring compares it with the project first (RestorePlan).

class pycal_dashboard.services.project_backup.ProjectBackup(project)#

Export a project as YAML, and restore a project from such a file.

The file has dashboard_backup, the version of its format, documentation, the address of the description of the format, the project with its name, description and step labels, its repositories, its filters, its steps with the skips of pull requests, its message with the edited one, and the members with their roles. tests/test_backup.py checks that every field that people decide is in it. Restoring is RestorePlan.

static documentation()#

The address of the description of the format.

data()#

The project as the file keeps it.

Returns:

The data, in the order of the file.

static skips(step)#

The skips of a step for pull requests, as the file keeps them.

Parameters:

step – The id of the step.

Returns:

Each with the repository and number of the pull request, by, the GitHub handle of who skipped it, the reason and when it was created.

message()#

The message of the tab PR Sync, as the file keeps it; None without one.

export()#

The backup as YAML, with a comment that says what it is.

Returns:

The text of the file.

static read(text)#

The data of a file, checked, before anything is changed.

Parameters:

text – The YAML.

Returns:

The data.

Raises:

What restoring a backup changes in a project; only what adds is made without a checkbox.

A backup is compared with the project before anything changes: what it adds, such as a new filter, is made at once; what deletes or replaces something, such as a filter that was added after the backup, is made only when the person ticks it. So restoring loses nothing unless the person says so.

pycal_dashboard.services.restore_plan.clean_name(value)#

A name of a file, on one line, as the site keeps names.

Parameters:

value – The value of the file.

Returns:

At most 100 characters.

Examples

>>> clean_name("  Peer\n review ")
'Peer review'
pycal_dashboard.services.restore_plan.color(value)#

The color of a step from a file: such as #bbf7d0, else none.

Parameters:

value – The value of the file.

Returns:

The color, or “”.

Examples

>>> color("#BBF7D0"), color("red; x"), color(None)
('#bbf7d0', '', '')
pycal_dashboard.services.restore_plan.step_fields(entry)#

The fields of a step of a file, as the site keeps them, without its filter.

Parameters:

entry – The step of the file.

Returns:

summary, hidden, color, conditions, actions and skip_authors.

pycal_dashboard.services.restore_plan.message_fields(entry)#

The fields of the message of a file, as the site keeps them.

Parameters:

entry – The message of the file.

Returns:

The fields of MESSAGE_FIELDS.

class pycal_dashboard.services.restore_plan.RestorePlan(project, data)#

The changes that a backup makes in a project, compared before anything is changed.

Filters and steps are the same when their names are: those of the file that the project lacks are added; those that differ are replaced, and those that the file lacks are deleted, each only when the person ticks it. The order of the steps changes only when ticked, too; new steps come last. The name, the description, the step labels and the message are replaced when ticked; roles are given only when ticked, as they are decisions about permissions. The skips of pull requests are added, and the repositories that the project lacks are added after it (repositories).

property repositories#

The repositories of the file that the project lacks, to add as the tab does.

compare()#

The changes, in the order in which they are shown.

Returns:

The changes; empty when the project has all of the file already.

compare_project()#

The name, the description and the step labels of the project.

Returns:

The changes of those that differ, each to tick.

compare_filters()#

The filters: added, replaced or deleted.

Returns:

The changes.

compare_steps()#

The steps: added, replaced, deleted, and their order.

Returns:

The changes.

compare_message()#

The message of the tab PR Sync: added, or replaced when it differs.

Returns:

The change, or none.

skips()#

The skips of the file that the project lacks and whose pull requests it knows.

Returns:

The name of the step, the pull request, the profile of who skipped it or None, and the skip of the file, with its reason and when it was created.

compare_skips()#

The skips of steps for pull requests that the project lacks.

Returns:

One change that adds them, or none.

compare_members()#

The roles of the file that differ: to tick, as they decide permissions.

Returns:

The changes, and a note for each person who never signed in.

apply(confirmed, user)#

Make the changes that only add, and those that the person ticked.

Parameters:
  • confirmed – The keys of the ticked changes; others that delete or replace stay.

  • user – The owner who restores.

Returns:

What could not be made, for the person.

apply_project(keys)#

Set the name, the description and the step labels, if ticked.

Parameters:

keys – The changes to make.

apply_deletions(keys)#

Delete the ticked steps and filters, with the step of a filter.

Parameters:

keys – The changes to make.

Returns:

Whether a step was deleted.

apply_filters(keys)#

Add the filters of the file, and replace those ticked.

Parameters:

keys – The changes to make.

apply_steps(keys, notes)#

Add the steps of the file, replace those ticked, and order them if ticked.

Parameters:
  • keys – The changes to make.

  • notes – What could not be made, which this adds to.

Returns:

Whether a step was added, replaced or moved.

apply_message()#

Set the message of the tab PR Sync; new pull requests are those from now on.

apply_skips()#

Add the skips of the file that the project lacks.

apply_members(keys, user, notes)#

Give the ticked roles, as an owner shares the project.

Parameters:
  • keys – The changes to make.

  • user – The owner who restores.

  • notes – What could not be made, which this adds to.

A change that restoring a backup makes in a project, such as adding or deleting a filter.

class pycal_dashboard.services.restore_change.RestoreChange(key, text, confirm=False, note=False)#

One change of RestorePlan.

key#

What it changes, such as filter-delete:Review: the value of its checkbox.

Type:

str

text#

What it does, for people, such as Delete the filter Review.

Type:

str

confirm#

Whether it deletes or replaces something: it is made only when the person ticks its checkbox. Changes that only add are made without.

Type:

bool

note#

Whether it is only said, such as a person who never signed in: nothing is made.

Type:

bool