Document the user workflow

.gitattributes

@@ -0,0 +1,4 @@
+* text=auto
+*.py text
+*.yaml text
+*.md text

.github/workflows/shell-check.yml

@@ -1,8 +1,5 @@
 
-on:
-  push:
-    branch:
-      - main
+on: [push, pull_request]
 
 name: 'Trigger: Push action'
 

CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to jitsuin-archivist #
+
+Thanks for taking the time to contribute to archivist-shell!
+
+Contributing is not limited to writing code and submitting a PR. Feel free to submit an
+[issue](https://github.com/jitsuin-inc/archivist-python/issues/new/choose) or comment on an existing one
+to report a bug, provide feedback, or suggest a new feature.
+
+Of course, contributing code is more than welcome! To keep things simple, if you're fixing a small issue,
+you can simply submit a PR and we will pick it up. However, if you're planning to submit a bigger PR to implement
+a new feature or fix a relatively complex bug, please open an issue that explains the change and the motivation for it.
+If you're addressing a bug, please explain how to reproduce it.
+
+## Pull request and git commit guidance
+
+### Opening PRs and organizing commits
+
+See the documented workflow described in the README.md file detailing the sequence of
+git commands required to submit a PR from a fork of this repo.
+
+PRs should generally address only 1 issue at a time. If you need to fix two bugs, open two separate PRs.
+This will keep the scope of your pull requests smaller and allow them to be reviewed and merged more quickly.
+
+When possible, fill out as much detail in the pull request template as is reasonable.
+Most important is to reference the GitHub issue that you are addressing with the PR.
+
+**NOTE:** GitHub has
+[a feature](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
+that will automatically close issues referenced with a keyword (such as "Fixes") by a PR or commit once the PR/commit is merged.
+Don't use these keywords. We don't want issues to be automatically closed. We want our testers to independently verify and close them.
+
+Generally, pull requests should consist of a single logical commit.
+However, if your PR is for a large feature, you may need a more logical breakdown of commits.
+This is fine as long as each commit is a single logical unit.
+
+### Writing good commit messages
+Git commit messages should explain the how and why of your change and be separated into a brief subject line
+followed by a more detailed body. When in doubt, follow this guide for good commit messages and
+you can’t go wrong: https://chris.beams.io/posts/git-commit/.
+
+One particularly useful point made in the above guide is regarding commit subject lines:
+
+> A properly formed Git commit subject line should always be able to complete the following sentence:
+> 
+> - If applied, this commit will <ins>your subject line here</ins>
+
+A simple but effective convention to follow for commits is the “problem / solution” pattern. It looks like this:
+```
+<Subject>
+
+Problem: <Statement of problem>
+
+Solution: <Statement of solution>
+```
+
+As an example, here is a commit taken from the rancher/rancher repo:
+```
+commit b71ce2892eecb7c87a5212e3486f1de899a694aa
+Author: Dan Ramich <danold215@gmail.com>
+Date:   Tue Jun 19 11:56:52 2018 -0700
+
+    Add Validator for RoleTemplate
+
+    Problem:
+    Builtin RoleTemplates can be updated through the API
+
+    Solution:
+    Add a Validator to ensure the only field that can be changed on a
+    builtin RoleTemplate is 'locked'
+```
+
+### Reviewing, addressing feedback, and merging
+Generally, pull requests need two approvals from maintainers to be merged.
+
+When addressing review feedback, it is helpful to the reviewer if additional changes are made in new commits.
+This allows the reviewer to easily see the delta between what they previously reviewed and the changes you added
+to address their feedback. These commits should be in the form of 'fixups' ('git commit --fixup HEAD').
+
+Once a PR has the necessary approvals, it can be merged.
+
+Here’s how the merge should be handled:
+- Once approved the author will be asked to squash all fixup commits generated by the review process.
+- Commits and their messages should be consistent - each commit in the PR should form a logical unit with working code. 
+- The first change requested by a Jitsuin reviewer will be to reorganise the commits into a clean logical structure.
+- The smaller a PR the more likely and more easily that the change will be approved.
+- Any changes requested by a reviewer should be committed as a 'fixup' commit against the original commit in the PR.
+- Once approval is granted any 'fixup' commits should be merged into their respective commits using 'git rebase -i --autosquash'.
+
+## Developer Certificate Of Origin ##
+
+To contribute to this project, you must agree to the Developer Certificate of Origin (DCO) for each commit you make.
+The DCO is a simple statement that you, as a contributor, have the legal right to make the contribution.
+
+See the [DCO](DCO) file for the full text of what you must agree to.
+
+To signify that you agree to the DCO for a commit, you add a line to the git
+commit message:
+
+```txt
+Signed-off-by: Jane Smith <jane.smith@example.com>
+```
+
+In most cases, you can add this signoff to your commit automatically with the
+`-s` flag to `git commit`. Please use your real name and a reachable email address.

README.md

@@ -1,18 +1,80 @@
 # archivist-shell
 
-Repository for convenience scripts for the Jitsuin Archivist system
+Repository for convenience scripts for the Jitsuin Archivist system.
 
 # Development
 
 ## Pre-requisites
 
 Required tools for this repo are task-runner and shellcheck.
 
-Install task runner: https://github.com/go-task/task
-Install shellcheck: https://github.com/koalaman/shellcheck#user-content-installing
+   - Install task runner: https://github.com/go-task/task
+   - Install shellcheck: https://github.com/koalaman/shellcheck#user-content-installing
 
 ## Workflow
 
+### Preparation
+
+Reference: https://gist.github.com/Chaser324/ce0505fbed06b947d962
+
+Fork the repo using the 'Fork' dialog at the top right corner of the github UI.
+
+Clone the new fork into your local development environment (assuming your github
+login is 'githubUserHandle'):
+
+> Note: all references to 'git@github.com' assume that your local github user has adequate
+> rights. If using ~/.ssh/config to manage ssh identities then replace all mentions of
+> 'git@github.com' with the clause name in ~/.ssh/config which references the appropriate
+> ssh key::
+> 
+> For example:
+```
+Host ssh-githubUserHandle
+    User git
+    Hostname github.com
+    PreferredAuthentications publickey
+    IdentityFile ~/.ssh/id_rsa_githubUserHandle
+
+Host ssh-otherUserHandle
+    User git
+    Hostname github.com
+    PreferredAuthentications publickey
+    IdentityFile ~/.ssh/id_rsa_otherUserHandle
+
+Host *
+    IdentitiesOnly yes
+
+```
+> i.e. 'githubUserHandle' viz:
+>
+>    git clone ssh-githubUserHandle:githubUserHandle/archivist-shell.git
+>
+
+
+```bash
+mkdir githubUserHandle
+cd githubUserHandle
+git clone ssh-githubUserHandle:githubUserHandle/archivist-shell.git
+```
+
+Enter the new cloned fork and add the original upstream repo as a remote:
+
+```bash
+cd archivist-shell
+git remote add upstream ssh-githubUserHandle:jitsuin-inc/archivist-shell.git
+git remote -v
+```
+
+Now add a branch for your proposed changes:
+
+```bash
+git status
+git checkout -b dev/githubUserHandle/some-proposed-fix
+git status
+```
+
+### Making changes
+
 To see what options are available simply execute:
 
 ```bash
@@ -25,4 +87,95 @@ Make a change to the code and validate the changes:
 task check
 ```
 
+### Seeking a review
+
+#### Synchronizing the upstream
+
+Bring in latest changes from upstream:
+
+```bash
+git fetch upstream
+git checkout main
+git pull --rebase upstream main
+git checkout dev/githubUserHandle/some-proposed-fix
+git rebase -i --autosquash main
+```
+> Caveat
+>
+> Note that we are rebasing to pull in upstream changes. This assumes that
+> the branch is only accessed/written by one person. If the branch is
+> collaborative the better option is to 'git merge main' as this is
+> safer but pollutes the git history with merge commits.
+> See https://www.atlassian.com/git/tutorials/merging-vs-rebasing#the-golden-rule-of-rebasing 
+>
+> This caveat applies to all occurrences of 'git rebase' in this document.
+
+
+Ensure that your email and name are correct:
+
+```bash
+git config user.name
+git config user.email
+```
+
+#### Pushing changes upstream
+
+Add all changes to a commit using the **example-commit** file as a template
+for the commit message.
+
+```bash
+git add .
+git commit
+```
+
+Push the changes upstream(the set-upstream option is only required the first time this is executed):
+
+```bash
+git push --set-upstream origin dev/githubUserHandle/some-proposed-fix
+```
+
+Enter the github ui at https://github.com/jitsuin-inc/archivist-shell and 
+generate a pull request.
+
+Reviewers will be notified when a PR is generated and you will receive feedback.
+Reviewers will trigger QC checks on your code. Failure will result in
+automatic rejection.
+
+#### Making further changes
+
+If changes are requested push the changes as a fixup:
+
+```bash
+git add .
+git commit --fixup HEAD
+git push
+```
+
+#### Removing Fixups After Reviewer Approval
+
+Eventually the reviewer(s) will approve your changes. At this point you must
+squash all your fixups after syncing upstream:
+
+```bash
+git fetch upstream
+git checkout main
+git pull --rebase upstream main
+git checkout dev/githubUserHandle/some-proposed-fix
+git rebase -i --autosquash main
+git push -f
+```
+
+#### PR is merged.
+
+The reviewer will then merge your PR into main.
+
+At this point one must tidy up the local fork:
+
+```bash
+git fetch upstream
+git checkout main
+git pull
+git log
+git branch -d dev/githubUserHandle/some-proposed-fix
+```
 

example-commit

@@ -0,0 +1,10 @@
+A meaningful concise title
+
+Problem:
+Clear succinct statement of problem.
+
+Solution:
+Summarised description of solution.
+
+Signed-off-by: User Name <user@email.com>
+