# 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](https://smallcultfollowing.com/babysteps/blog/2023/10/20/using-rust/#fnref:3) from [wg-async](https://rust-lang.github.io/wg-async/vision/characters.html)  

* 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