aljaz/pear-docs
1
0
Fork 0
mirror of https://github.com/aljazceru/pear-docs.git synced 2025-12-17 06:24:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fix 'key' vs 'link' (#149)

Browse Source 
* Change `key` to `link` to match CLI functionality

CLI commands have changed to take the link format (`pear://<key>`)
instead of the key.

* Update guides to use `link` instead of `key` for CLI commands
This commit is contained in:
Sean Zellmer
2024-10-19 10:10:21 -05:00
committed by GitHub
parent 040acadf22
commit 174dcce808
3 changed files with 37 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
guide/releasing-a-pear-app.md
View File

@@ -6,11 +6,11 @@ Each version is identified by `<fork>.<length>.<key>`. The length corresponds to
{% embed url="https://www.youtube.com/watch?v=OTwY_avUPyI" %} Build with Pear - Episode 03: Releasing Pear Applications {% embeded %}
`pear run <key>` opens the application.
`pear run <link>` opens the application.
Before a release has been marked, the latest version is used. This is useful during development, to test the app locally and to share a preview with other peers.
Once a release has been marked, `pear run <key>` opens the latest marked release.
Once a release has been marked, `pear run <link>` opens the latest marked release.
## Step 1: Staging Production
@@ -22,13 +22,13 @@ For example, a `pear stage dev` release channel used during development can be c
pear stage production
```
Running this command in a Pear project folder outputs an application key.
Running this command in a Pear project folder outputs an application link.
Using separate channels for development and production means there is an application key for trusted peers and one for public peers.
Using separate channels for development and production means there is an application link for trusted peers and one for public peers.
The development key can remain unreleased, so that `pear run <dev key>` loads the latest staged changes by default.
The development link can remain unreleased, so that `pear run <dev link>` loads the latest staged changes by default.
The production key's releases can be marked, so that `pear run <production key>` loads the latest stable release by default.
The production link's releases can be marked, so that `pear run <production link>` loads the latest stable release by default.
## Step 2: Marking a Release
@@ -56,12 +56,12 @@ First verify that it works by running `pear run --dev .`
Now stage the change with `pear stage production`.
Opening the application with `pear run <key>` will **not** output the log, because it loads the latest **marked** release.
Opening the application with `pear run <link>` will **not** output the log, because it loads the latest **marked** release.
The latest staged changes of a released application can be previewed with the `--checkout` flag:
```
pear run <key> --checkout=staged
pear run <link> --checkout=staged
```
The value of the `--checkout` flag may be `staged`, `released` (the default) or a number referring to a specific version length.
@@ -70,16 +70,16 @@ The value of the `--checkout` flag may be `staged`, `released` (the default) or
### The dump-stage-release strategy
A development application key can be shared among trusted peers. At that point, it could be referred to as an internal application key (internal to the group of peers who have the key).
A development application link can be shared among trusted peers. At that point, it could be referred to as an internal application link (internal to the group of peers who have the link).
While using different channel names is sensible, using `pear stage dev` and `pear stage production` on the same machine has practical implications.
A dump-stage-release strategy seperates the concerns between development and production, by using a different machine for each.
On the machine that holds the production key, run:
On the machine that holds the production link, run:
```
pear dump <internal-key> <path-to-app-production-dir>
pear dump <internal-link> <path-to-app-production-dir>
```
This is a reverse stage: it synchronizes the application files to disk.
@@ -108,4 +108,4 @@ Asset building of distribution packages (.dmg, .msi, .appimage) is not yet possi
* [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)
* [Sharing a Pear Application](./sharing-a-pear-app.md)

22
guide/sharing-a-pear-app.md
View File

@@ -18,7 +18,7 @@ If starting from [Making a Pear Desktop Application](./making-a-pear-desktop-app
To view the help for the `pear stage` command run `pear help stage`.
The command signature for `pear stage` is `pear stage <channel|key> [dir]`.
The command signature for `pear stage` is `pear stage <channel|link> [dir]`.
Before a project is staged for the first time there is no key. The application name and `channel` name are involved in generating the application key, which is later used to run the application from the DHT.
@@ -32,7 +32,7 @@ No need to specify `dir`, the command-line current working directory is already
The channel name can be any valid name. Using `dev` for local development checks and internal collaboration, using `pear stage production` for production and `pear stage <custom-channel-name>` for any customizations/specializations of the application is a reasonable convention.
Stage will output a diff of changes - the first time will all be additions of course - and then it will output the application key.
Stage will output a diff of changes - the first time will all be additions of course - and then it will output the application link.
If the application is a desktop application there will also be a warmup step where the application is opened in the background and analyzed for initialization-to-loaded critical-path. This metadata is stored along with the application into an application-dedicated hypercore inside Pear. This helps the desktop application load faster. All state is local and by default only the original machine that stages an application can write to this application-dedicated hypercore.
@@ -42,9 +42,9 @@ If the application is a desktop application there will also be a warmup step whe
To view the help for the `pear run` command run `pear help run`.
The command signature for `pear run` is `pear run <key>`.
The command signature for `pear run` is `pear run <link>`.
Copy the application key that was output when the application was staged in the prior step and pass it to `pear run`. For example, if the application key was `pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o` the command to run would be:
Copy the application link that was output when the application was staged in the prior step and pass it to `pear run`. For example, if the application link was `pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o` the command to run would be:
```
pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
@@ -54,11 +54,11 @@ pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
## Step 3. Seed the app
The application can be shared with other peers by announcing the application to the DHT and then supplying the application key to other peers.
The application can be shared with other peers by announcing the application to the DHT and then supplying the application link to other peers.
To view the help for the `pear seed` command run `pear help seed`.
The command signature for `pear seed` is `pear seed <channel|key> [dir]`.
The command signature for `pear seed` is `pear seed <channel|link> [dir]`.
The staged application can be seeded with:
@@ -87,7 +87,7 @@ As long as the process is running the application is being seeded. If other peer
It's important that the application seeding process from the former step is up and running otherwise peers will not be able to reach connect and replicate state.
With another machine or friend that has `pear` installed execute the `pear run <key>` command to load the application directly peer-to-peer. So with the same example application key it would be:
With another machine or friend that has `pear` installed execute the `pear run <link>` command to load the application directly peer-to-peer. So with the same example application link it would be:
```
pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
@@ -128,7 +128,7 @@ The application staging machine that is running the seeding process should show
•-• peer join 8054f613d911b990834a0234507447c8ca88f4e778594c0e4fc480a314dc6d62
```
The `peer join` line displays the remote public key, in hex, of the peer that executed `pear run` with the application key.
The `peer join` line displays the remote public key, in hex, of the peer that executed `pear run` with the application link.
Once the application is closed on the peer machine the seeding output on the original machine will be similar to:
@@ -152,13 +152,13 @@ When Pear loads an application from a peer the staged files are sparsely replica
#### Reseeding
The command signature for `pear seed` is `pear seed <channel|key> [dir]`.
The command signature for `pear seed` is `pear seed <channel|link> [dir]`.
If the application was staged on the machine, it will seed the appliction from the machine.
Otherwise, passing an application key to `pear seed` will reseed the application from that key.
Otherwise, passing an application link to `pear seed` will reseed the application from that link.
For example, given the key `pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o`, executing `pear seed pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o` on a peer that didn't originally stage that particular application will result in that process syncing up-to-date data from peers and providing it to peers who need it.
For example, given the link `pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o`, executing `pear seed pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o` on a peer that didn't originally stage that particular application will result in that process syncing up-to-date data from peers and providing it to peers who need it.
Once an application is being reseeded, the original seeding process can be closed on the staging machine. However any newly staged changes have to be seeded from that machine for reseeders to pick them up. Which means `pear seed` can be used "deploy" to reseeders by starting after staging, leaving it running until reseeders have synced and then stopping the process again.

28
reference/pear/cli.md
View File

@@ -36,14 +36,14 @@ Alias for: `pear run --dev <dir>`
--store|-s=path Set the Application Storage path
--tmp-store|-t Automatic new tmp folder as store path
```
## `pear stage <channel|key> [dir]`
## `pear stage <channel|link> [dir]`
Synchronize local changes to key.
Synchronize local changes to channel or key.
Channel name must be specified on first stage,
in order to generate the initial key.
Outputs diff information and project key.
Outputs diff information and project link.
```
--json Newline delimited JSON output
@@ -55,13 +55,11 @@ Outputs diff information and project key.
--help|-h Show help
```
## `pear seed <channel|key> [dir]`
## `pear seed <channel|link> [dir]`
Seed project or reseed key.
Specify channel or key to seed a project.
Specify a remote key to reseed.
Specify channel or link to seed a project or a remote link to reseed.
```
--json Newline delimited JSON output
@@ -74,7 +72,7 @@ Specify a remote key to reseed.
## `pear run [flags] <link|dir> [...app-args]`
Run an application from a key or dir.
Run an application from a link or dir.
| | |
|-------|---------------------------------------------------|
@@ -122,7 +120,7 @@ pear run -t file://path/to/an-app-folder --some app --args
pear run pear://keet
```
## `pear release <channel|key> [dir]`
## `pear release <channel|link> [dir]`
Set production release version.
@@ -136,11 +134,11 @@ Use this to indicate production release points.
--help|-h Show help
```
## `pear info [channel|key]`
## `pear info [link|channel]`
Read project information.
Supply a key or channel to view application information.
Supply a link or channel to view application information.
Supply no argument to view platform information.
@@ -148,7 +146,7 @@ Supply no argument to view platform information.
--changelog View changelog only
--full-changelog Full record of changes
--metadata View metadata only
--key View key only
--key View link only
--json Newline delimited JSON output
--no-ask Suppress permissions dialogs
--help|-h Show help
@@ -156,7 +154,7 @@ Supply no argument to view platform information.
## `pear dump [flags] <link> <dir>`
Synchronize files from key to dir.
Synchronize files from link to dir.
> To dump to stdout use `-` in place of `<dir>`
@@ -204,10 +202,12 @@ Output version information.
--help|-h Show help
```
## `pear shift <src-key> <dst-key> [--force]`
## `pear shift [flags] <source> <destination>`
Move user application storage between applications.
`<source>` and `<destination>` are links.
```
--force Overwrite existing application storage if present
--json Newline delimited JSON output