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_backupThe 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.
documentationThe address of this page.
exported,siteWhen and where the backup was made; restoring does not read them.
projectnameanddescription(Markdown),step_labels(offorsync, see PR Sync), andslugandpublic, which restoring leaves as they are: the address and the visibility of the project.repositoriesThe 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.filtersThe saved filters, each with its
name, unique in the file, itsdescriptionand itscolumns: the columns of conditions as the address of the table keeps them, see Columns of conditions.stepsThe steps from left to right, each with its
name, the name of itsfilterin the file, itssummary, whether it ishiddenin the page of a pull request, itscolor(such as#bfdbfe, or empty), thetasks(thesummaryanddescriptionof each condition of its filter, by the column) and itsactions: the labels toaddand toremovewhen a pull request willenterthe step orcompleteit, andskip_authors, the GitHub handles of the authors whose pull requests skip it. Itsskipsare the pull requests that skip it because a person said so: therepositoryandnumberof the pull request, the GitHub handle of the person (by), thereasonand when it wascreated.messageThe 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 requestslistedby their numbers, and the switches of its scope,to_listed,to_new,to_openandto_closed; empty without a message. New pull requests count from the time of restoring.membersThe roles in the project: the GitHub
handleof each person and therole,read,writeorowner.
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, theprojectwith its name, description and step labels, itsrepositories, itsfilters, itsstepswith the skips of pull requests, itsmessagewith the edited one, and thememberswith their roles.tests/test_backup.pychecks that every field that people decide is in it. Restoring isRestorePlan.- 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
repositoryandnumberof the pull request,by, the GitHub handle of who skipped it, thereasonand when it wascreated.
- 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:
BackupInvalid – It is no YAML, too large, or a part is missing or wrong.
BackupVersionUnknown – Its version is not that of this site.
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,actionsandskip_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
reasonand when it wascreated.
- 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.- 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: