OS X/WSL user stories [Was: Windows, OS X]

[Richard Maw <richard maw codethink co uk>]

Our team had a go at hashing out user stories for the issues.
https://gitlab.com/BuildStream/buildstream/issues/411
https://gitlab.com/BuildStream/buildstream/issues/412

We'd appreciate feedback.

Apologies if it's not formatted as you'd normally take user stories.

# User stories

## Setting up BuildStream

Assumption: There's a canonical "upstream" download page.

Assumption: Downloads are accompanied by a gpg signature file signed by a BuildStream maintainer private key 
with a well known public key.

Assumption: If a remote worker is required on the same machine then it has already been provisioned.

The user or system administrator navigates to the BuildStream download page, and downloads the package for 
the latest version and the signature file.
The integrity of the package is verified by checking its contents against the signature provided by the 
signature file.

<!-- NOTE: This glosses over distribution of the well known public key or exactly how the signature is 
created and verified -->

If the BuildStream package's signature wasn't already verified on the target machine, it is copied on to the 
target machine and installed.

<!-- NOTE: Probably a .dpkg targeting a stable Ubuntu in WSL and a .dmg on OSX -->

Once the package is installed `bst --help` is run in a terminal to ensure the command can be found and 
dependent libraries are installed.

Before attempting to start any builds the user follows instructions in 
https://buildstream.gitlab.io/buildstream/install_artifacts.html#configuring-buildstream-to-use-remote-caches 
to configure a remote artifact cache, tweaks any configuration as described in 
https://buildstream.gitlab.io/buildstream/using_config.html#default-configuration and configures any remote 
workers.

## Developing a component

Assumption: We are working from a terminal emulator running a unix
shell (through WSL, if necessary), and have a buildstream project that
we acquired through some external means.

When a user develops a component using BuildStream on macOS or
Windows, they will want to:

### Open workspaces
   To start development on a component, we will want to create a
   workspace using `bst workspace open`, which should make the sources
   of the component available in a directory for us to work on.

### Modifying the component
   We will want to use the directory resulting from the previous step
   as if it was exactly the same we would have received when
   developing normally - i.e., we would like to be able to run
   commands such as `git commit` or `git blame` without having to jump
   through further hoops.

### Building the component
   To test our work, we will want to build the component. For this we
   will invoke `bst build`, and we would like this to give us all
   information a normal, manual build would have given us.

   For most build systems, this means displaying build logs in real
   time.

### Debugging the component
   To debug the component, we would like to have a shell capable of
   running our build and the resulting element. This should be
   accessible through `bst shell -b` and `bst shell` respectively.

### Deploying a component

After a build has been completed successfully the cached artifact can be made available with `bst checkout 
$element $directory` with the contents of the artifact being available in `$directory`.

The produced files can be subjected to tests appropriate to the kind of software they are.

Once verified to be correct they can be deployed into production.

### Updating buildstream

When a new release of BuildStream is made it is announced on the mailing list.

Check release notes before performing an update for extra update steps, but this should not normally be 
needed.

Download, verify and install a new version of the BuildStream package as described earlier.

Follow any additional update steps as described by the release notes.
This may involve configuration updates, but redefining the configuration that was performed on first install 
should not be necessary.