Pijul requirements

User-friendly

• user must feel that pijul is fast
• user must see clear error messages
• user must have mental model map of .pijul implementation
• user must read good documentation
• user must feel it's easy to install
• user must feel interface is consistent
• user must feel terminology is consistent
• user must feel design is consistent
• user must read interface in i18n languages

Robust

• user must read theoretically sound writeup
• user must resolve conflicts natively
• user must use monorepo workflow
• user must use multirepo workflow

Tooling

• user must get machine-readable output for every command
• user can integrate pijul into a command line server like soft-serve
• user can track issues alongside alongside the code like fossil
• user must read good documentation for the process of integration
• user must feel that API is clear
• user must see clear API for cloning
• user must see clear API for remote management
• user must see clear API for identity management
• user must see clear API for conflict resolution
• user must see clear API for change history

Repositories

• user must initialize a repository
• user must see automatically generated .pijul directory
• user must see automatically generated .ignore file
• user must see useful defaults in generated .ignore file
• user must see .DS_Store in generated .ignore file on MacOS
• user must see .git in generated .ignore file if directory has .git
• user must clone a repository
• user must clone a repository over ssh
• user must clone a repository over https
• user must see new directory with repository name
• user must download project files from remote
• user must download .pijul from remote
• user must download .ignore from remote
• user must import .git repository to .pijul repository

Identities

• user must create identity
• user must feel it's easy to create identity
• user must manage multiple identities
• user must modify display name
• user must modify identity name
• user must modify email
• user won't modify encryption
• user won't modify expiry
• user must modify remote
• user must feel it's secure to use an identity
• user must use passphrases to secure identity
• user must rotate key
• user must revoke key

Remotes

• user must add a remote
• user must edit a remote
• user must remove a remove
• user must feel it's easy to manage remote
• user must read good documentation
• user must self-host over ssh
• user must self-host over https
• user must have different patch sets on remote A and remote B
• user must push over ssh
• user must push over https
• user must pull over ssh
• user must pull over https

Changes

• user must see modifications that are not yet recorded in a change
• user must learn that working dir is recorded directly, there's no staging area
• user must pick which patches for each file to record change
• user must split changes into multiple smaller changes
• user must amend previous changes with new metadata
• user must amend previous changes with new patches
• user must sign changes with identity
• user must track a file
• user must track all files in a project pijul add -r .
• user must track a directory
• user must track all files in a directory
• user must record tracked changes
• user must record tracked changes with a custom message
• user must ignore a file from tracking
• user must see list of files not tracked and not ignored

Sets of changes

• user must compare sets of changes against each other
• user must compare changes between two versions from history
• user must compare single change to set of changes
• user must see name of current version of repository, channel
• user must tag, compress set of changes into snapshot
• user must merge two sets of changes

Files

• user must track file
• user must untrack file
• user must add a directory recursively
• user must see how many files were tracked
• user must see how many new changes are tracked
• user won't see notification "tracked 1 path" if the file is already tracked
• user must rename a file
• user must track renamed file
• user must move a file
• user must delete a file
• user must purge file from history like git filter-repo
• user must list tracked files
• user must list untracked files
• user must list tracked status of all files
• user must ignore a file user via .ignore

CLI

• user must view status/summary of repository
• user must use cli in system language according to 18n
• french user must see french text in cli
• user must feel the CLI terminology and idioms are consistent
• user must view log of all changes
• user must view log of most recent change
• user must view modification history of changes
• user must see when a change is created
• user must see when a change amended to include added file
• user must see when a change is unrecorded
• user must compare differences with remote

Maintainers

• maintainer must download user-submitted changes
• maintainer must be able to edit directory after downloading user-submitted changes
• maintainer must propose amendment to title and description without author input
• maintainer should amend title and description without author input
• maintainer should add author credit to changes not signed by original author
• maintainer must rewrite history of changes

Deprecated

• user must see error "pijul key" has been deprecated. Please run "pijul identity" instead. for a deprecated command

cast of characters

standing on the shoulders of giants from wg-async

• Alan: the experienced git user, new to pijul
  • Top priority: conflict resolution -- that's what he is not getting from git
  • Expectations: absence of hard to resolve conflicts (he gets that now from his git), strong ecosystem, great tooling
• Grace: the darcs expert, new to pijul
  • Top priority: clear mental model -- that's what she was not getting from darcs
  • Expectations: able to do all the magical things she's used to from darcs
• Niklaus: new user from an unconventional background
  • Top priority: accessibility -- he's learning a lot of new things at once
  • Expectations: community -- the community enabled him to have early success, and he is excited to have it support him and him grow more
• Barbara: the experienced pijul user
  • Top priority: overall productivity and long-term maintenance -- she loves pijul, and wants to see it extended to new areas; she has an existing pijul repository to maintain
  • Expectations: elegance and craftsmanship, fits well with pijul