.doing.md
# CLI Bootstrap Notes
TODO:
- [ ] Which subset of features to start with?
- [ ] How to integrate smoothly with Git/Github features of Atom.
### Affordances
Author
- init/update (fetch, attempt to rebase)
- auto-save (auto-commit to autosave branch v0.x.x-auto-y)
- save (squash auto-commits with new message, how far back? parse auto commit messages?)
- save as (squash auto-commits with new message to named branch, autosave v0.x.x-branch-name-y)
- load (named branches, possibly previous autosaves, versions)
- sync (push local branches to user fork)
- submit (send PR)
Publisher
- publish (merge PR)
### Implementaiton
Workspace is for content folder access and manipulation.
`.content` should have the git checkout instead of the module. ~~Possibly there could be a read only mode where we use the module. (let's not to keep things simple)~~
Assumptions:
- Gitlab? Github?
- Personal forks are not shared. (so rebase to main repo are ok)
init should:
- check for existing access to git user info.
- if not, display instructions.
- check for existing user fork for content packages.
- if not, display instructions and URL to create fork.
- clone the fork (declared in the content.yml of the CLI tool).
- Checkout tag (i.e. published version), not master.
start/update should check for changes and:
- no changes: `git pull`
- check changes on startup.
- fetch master and tags, new tag?
- if new tag, try to rebase new tag onto auto-save branch.
- deal with conflicts.
- if succeed create new autosave branch with new tag version?
- if new commits on master, try to fast forward master onto auto-save branch
- auto-save
- `metalsmith-contentascode-autosave`
- Auto-commit can be annoying because of lack of messages and control over granularity. (squashing on save should address this)
- Editor auto-saving in the editor should be enabled. (i.e. autofile save, irrespective of auto-commit)
- Auto-commit in a personal autosave branch and push on exit (and/or every 5 minutes) might be a good safety feature.
- Then squashing auto-commits from the autosave branch
- save to branch (v0.x.x-auto-y)
Autosave branch switches from a named-branch:
- When new "save as" to new named branch
- After load of other named branch or of version tag.
When is increment useful? When reloading tag and starting to work which avoids loosing autosaves from previous session. So increment should occur on "save as" and "load".
Model:
- Current tag. (tip of minor release? what about when merge is happening?)
- Current autosave branch (v0.x.x-auto-y or v0.x.x-named-save-y).
#### Minimum
- init/update:
- check if new tags:
- If yes, then this is a major/minor update.
- check if release branch has advanced. (Can we avoid this on the first version?)
- If yes, then this is a patch update.
- If both, then do only major/minor update, but if it fails try patch update.
- If major/minor update (from v0.a to v0.b):
- Double check with the user what the current local version is. Show all autosave branches? only the most recent? only the "current" one?
- Create new incremented local version from current local version (v0-a-my-save-321) with new version as base branch name using tag name conversion convention (v0-b-my-save-322)
- Rebase new release branch (upstream v0-b) onto renamed current local version (v0-b-my-save-322)
- Deal with conflicts
- Switch to updated (rebased, renamed, incremented) v0-b-my-save-321
- If patch update (from v0.a.x to v0.a.y)
- Double check with the user what the current local version is. Show all autosave branches? only the most recent? only the "current" one?
- Create new incremented local version from current local version (v0-a-my-save-321) i.e. (v0-a-my-save-322)
- Rebase fetched current release branch (upstream v0-a) onto current local version (v0-a-my-save-322)
- Deal with conflicts
- Switch to updated (rebased, incremented) v0-a-my-save-322
- save:
- Best UI would be to trigger this from an atom pane web preview, a browser based web preview. (display number of changes in badge on "Save" button). Save would then open the Git tab and focus on the commit message box in Atom. Or, the web preview would open a message box, and confirming would send a payload via websocket to a metalsmith plugin.
- ??? fetch upstream to pre-empt stale PR ?
- Enter commit message.
- Attempt to push to remote fork.
- Ask if want to **submit** change.
- If yes, then offer instructions.
#### Deal with conflicts
- Detect `error: could not apply fa39187` somehow.
- Open Atom in Merge Conflict mode.
- Continue (or Abort).
- `git rebase --continue`
### Broader questions
Do we need release branches (usually needed for non-SaaS distributed software packages) because of the possible content dependency network? With them it might allow:
- To push hotfixes more easily by having dependents merge the tip of the branch.
This really depends on whether:
- everything is doable just with tags? (Seems that not).
- there is a strategy for obsolescense of versions. (ping back with transclusion client?)
- how this mixes with npm publishing (should be fine).
Ping back with transclusion client if it includes fork name would allow to alert authors of conflicting changes or people working on same content before merge.