releasing a pear, readme iterate, howtos

guide/connecting-many-peers.md

@@ -1,4 +1,4 @@
-### Hyperswarm: Connecting to Many Peers by Topic
+### How to connect to many peers by topic with Hyperswarm
 
 Get setup by creating a project folder and installing dependencies:
 

guide/connecting-two-peers.md

@@ -1,5 +1,5 @@
 
-### Hyperswarm's DHT: Connecting Two Peers by Key
+### How to connect two Peers by key with Hyperdht
 
 Get setup by creating a project folder and installing dependencies:
 

guide/corestore.md

@@ -1,5 +1,5 @@
 
-### Corestore: Working with Many Hypercores
+### How to work with many Hypercores using Corestore
 
 Get setup by creating a project folder and installing dependencies:
 

guide/hyperbee.md

@@ -1,5 +1,6 @@
 
-### Hyperbee: Sharing Append-Only Databases
+### How to share Append-Only Databases with Hyperbee
+
 Get setup by creating a project folder and installing dependencies:
 
 ```bash
@@ -85,7 +86,7 @@ async function loadDictionary() {
 ```
 
 
-`bee-reader.js` creates a Corestore instance and replicates it using the Hyperswarm instance to the same topic as the above file. On every word entered in the command line, it will download the respective data to the local Hyperbee instance.
+`bee-reader.js` creates a Corestore instance and replicates it using the Hyperswarm instance to the same topic as `writer.js`. On every word entered in the command line, it will download the respective data to the local Hyperbee instance.
 
 Try looking at disk space the `reader-storage` directory is using after each query. notice that it's significantly smaller than `writer-storage`! This is because Hyperbee only downloads the Hypercore blocks it needs to satisfy each query, a feature we call **sparse downloading.**
 

guide/hypercore.md

@@ -1,4 +1,4 @@
-### Hypercore: The Basics
+### How to replicate and persist with Hypercore
 
 Get setup by creating a project folder and installing dependencies:
 

guide/hyperdrive.md

@@ -1,6 +1,4 @@
-
-
-### Hyperdrive: A Full P2P Filesystem
+### How to create a full P2P filesystem with Hyperdrive
 
 Get setup by creating a project folder and installing dependencies:
 

guide/releasing-a-pear-app.md

@@ -1,21 +1,95 @@
 # Releasing a Pear Application
 
-As covered in [Sharing a Pear App](./sharing-a-pear-app.md), Pear use release channels in a similar way that git use branches. When the app has been tested, and it's ready to release it, it's really simple.
+Pear Applications are stored in an append-only log ([hypercore](../building-blocks/hypercore.md)) and the log has a length.
 
+Pear versions takes the form `<fork>.<length>.<key>`. The version length of a Pear application is the length of its append-only log.
 
-* prerelease strategy
-* dump strategy
+When an application has not been marked with a release, `pear run <key>` opens the the application at its latest version length. This is excellent in development, both locally and for other peers to preview prereleased work.
 
-## Previewing prerelease 
+However, once a release has been marked `pear run <key>` will only open the latest marked release.
 
-## Marking a Release
+## Step 1: Staging Production
 
-Assume that the app was staged into `example`, then releasing it is simply:
+The `pear stage` command derives an application key from the application name as defined in the project `package.json` file and the specified `channel` name. The `pear stage dev` convention for development can be complemented with a `production` channel name for production. Running the following command in a Pear Project folder will output an application key.
 
-```
-pear release example
+```sh
+pear stage production
 ```
 
-This moves the example channel to the released version. The seeders who are already seeding that channel, will still be seeding.
+Using separate channels for development and production means there's an application key for trusted peers and an application key for public peers. The development key can remain unreleased so that `pear run <key>` loads the latest staged changes by default while releases can be marked on the production key so that `pear run <key>` loads the latest stable release by default for production.
 
-## Dump to Stage Production Key Deployment Strategy
+## Step 2: Marking a Release
+
+Changes to an application can only propagate to peers if the application is being seeded:
+
+```
+pear seed production
+```
+
+To view the help for the `pear release` command run `pear release help`.
+
+To indicate the latest staged changes on the production channel is at a release point run:
+
+```
+pear release production
+```
+
+## Step 3: Running staged from a released app
+
+After marking a release, make a trivial change to the project (e.g. add a console.log somewhere), check it works with the `pear dev` command and then stage it with `pear stage production`.
+
+Opening the application with `pear run <key>` will **not** result in the log being output because `pear run` will load the latest marked release before the added log was staged.
+
+The latest staged changes on a released application can be previewed using the `--checkout` flag:
+
+```
+pear run <key> --checkout=staged
+```
+
+The value of the `--checkout` flag may be `staged`, `released` (default) or a number representing the specific version length to checkout.
+
+## Discussion
+
+### The dump-stage-release strategy
+
+A development application key can be shared among trusted peers - at which point it could be referred to as an internal application key (internal to that group of peers who have the key).
+
+While using different channel names by convention makes good sense, using `pear stage dev` and `pear stage production`  on the same machine can have practical limitations.
+
+A dump-stage-release strategy can be employed to futher seperate the concerns between development and production and enable different machines to own internal vs production keys.
+
+The machine that will hold the production key can run:
+
+```
+pear dump <internal-key> <path-to-app-production-dir>
+```
+
+This will synchronize the application files to disk. It's a reverse stage.
+
+Once complete the project can be staged from the production machine with:
+
+```
+pear stage production
+```
+
+Then released with:
+
+```
+pear release production
+```
+
+A `pear seed production` process would also need to be running for other peers to access the application.
+
+The same three commands in order, `pear dump`, `pear stage` and `pear release`, can be used to carve a release from an internal key to a production key across different machines at any time.
+
+### Distribution Packages
+
+Asset-building of Distribution Packages (.dmg, .msi, .appimage) is currently not featured by Pear but is a feature for the future.
+
+## Next
+
+* [Starting a Pear Desktop Project](./starting-a-pear-desktop-project.md)
+* [Making a Pear Desktop Application](./making-a-pear-desktop-app.md)
+* [Starting a Pear Terminal Project](./starting-a-pear-terminal-project.md)
+* [Making a Pear Terminal Application](./making-a-pear-terminal-app.md)
+* [Sharing a Pear Application](./sharing-a-pear-app.md)

guide/sharing-a-pear-app.md

@@ -14,7 +14,7 @@ If starting from [Making a Pear Desktop Application](./making-a-pear-desktop-app
 
 ## Step 1. Stage the app
 
-To view the help for the `pear stage` command we can run `pear stage help`.
+To view the help for the `pear stage` command run `pear stage help`.
 
 The command signature for `pear stage` is `pear stage <channel|key> [dir]`.
 
@@ -38,7 +38,7 @@ If the application is a desktop application there will also be a warmup step whe
 
 ## Step 2. Run the app on the same machine
 
-To view the help for the `pear run` command we can run `pear run help`.
+To view the help for the `pear run` command run `pear run help`.
 
 The command signature for `pear run` is `pear run <key>`.
 
@@ -54,7 +54,7 @@ Where `pear dev` opens an application from the filesystem, `pear run`  opens the
 
 The application can be shared with other peers by announcing the application to the DHT and then supplying the application key to other peers.
 
-To view the help for the `pear seed` command we can run `pear seed help`.
+To view the help for the `pear seed` command run `pear seed help`.
 
 The command signature for `pear seed` is `pear seed <channel|key> [dir]`.