fix: apply review suggestions

AuHau · daviddias · AuHau · commit a3d17127973c · 2019-10-10T17:35:56.000+02:00
Co-Authored-By: David Dias &lt;daviddias.p@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@ This framework:
  * Defines migrations API
  * Executes and reports migrations in both directions: forward and backward
  * Simplifies creation of new migrations
+ * Works on the browser too!
 
 ## Install
 
@@ -89,11 +90,61 @@ if(repoVersion < migrations.getLatestMigrationVersion()){
 
 To migrate your repository using the CLI, see the [how to run migrations](./run.md) tutorial. 
 
-**For tools that build on top of `js-ipfs` and run mainly in the browser environment, be aware that disabling automatic
-migrations leaves the user with no way to run the migrations because there is no CLI in the browser. In such
-a case, you should provide a way to trigger migrations manually.**
+## API
+
+### `.migrate(path, {toVersion, ignoreLock, repoOptions, onProgress, isDryRun}) -> Promise<void>`
+
+Executes a forward migration to a specific version, or to the latest version if a specific version is not specified.
+
+**Arguments:**
+
+ * `path` (string, mandatory) - path to the repo to be migrated
+ * `options` (object, optional) - options for the migration
+ * `options.toVersion` (int, optional) - version to which the repo should be migrated. Defaults to the latest migration version.
+ * `options.ignoreLock` (bool, optional) - if true will not lock the repo when applying migrations. Use with caution.
+ * `options.repoOptions` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
+ * `options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
+ * `options.isDryRun` (bool, optional) - flag that indicates if it is a dry run that should give the same output as running a migration but without making any actual changes.
+ 
+#### `onProgress(migration, counter, totalMigrations)`
+ 
+Signature of the progress callback.
+
+**Arguments:**
+ * `migration` (object) - object of migration that just successfully finished running. See [Architecture of migrations](#architecture-of-migrations) for details.
+ * `counter` (int) - index of current migration.
+ * `totalMigrations` (int) - total count of migrations that will be run.
+
+### `.revert(path, toVersion, {ignoreLock, options, onProgress, isDryRun}) -> Promise<void>`
+
+Executes backward migration to a specific version.
+
+**Arguments:**
+
+ * `path` (string, mandatory) - path to the repo to be reverted
+ * `toVersion` (int, mandatory) - version to which the repo should be reverted to. 
+ * `options` (object, optional) - options for the reversion
+ * `options.ignoreLock` (bool, optional) - if true will not lock the repo when applying migrations. Use with caution.
+ * `options.options` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
+ * `options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
+ * `options.isDryRun` (bool, optional) - flag that indicates if it is a dry run that should give the same output as running a migration but without making any actual changes.
+ 
+### `getLatestMigrationVersion() -> int`
 
-### Writing migration
+Return the version of the latest migration.
+
+## CLI
+
+The CLI is a NodeJS binary named `jsipfs-repo-migrations`. 
+It has several commands:
+
+ * `migrate` - performs forward/backward migration to specific or latest version.
+ * `status` - check repo for migrations that should be run.
+ * `add` - bootstraps new migration.
+ 
+For further details see the `--help` pages.
+
+## Creating a new migration
 
 Migrations are one of those things that can be extremely painful on users. At the end of the day, we want users never to have to think about it. The process should be:
 
@@ -106,7 +157,7 @@ If your migration has several parts, it should be fail-proof enough that if one
 are reverted before propagating the error. If possible then the outcome should be consistent repo so it migration could
 be run again. 
 
-#### Architecture of migrations
+### Architecture of a migration
 
 All migrations are placed in the `/migrations` folder. Each folder there represents one migration that follows the migration
 API.
@@ -122,7 +173,7 @@ Each migration must follow this API. It must export an object in its `index.js`
  * `migrate` (function) - Function that performs the migration (see signature of this function below)
  * `revert` (function) - If defined then this function will revert the migration to the previous version. Otherwise it is assumed that it is not possible to revert this migration.
 
-##### `migrate(repoPath, isBrowser)`
+#### `.migrate(repoPath, isBrowser)`
 
 _Do not confuse this function with the `require('ipfs-repo-migrations').migrate()` function that drives the whole migration process!_
 
@@ -131,7 +182,7 @@ Arguments:
  * `options` (object, optional) - object containing `IPFSRepo` options, that should be used to construct a datastore instance.
  * `isBrowser` (bool) - indicates if the migration is run in a browser environment (as opposed to NodeJS)
  
-##### `revert(repoPath, isBrowser)`
+#### `.revert(repoPath, isBrowser)`
 
 _Do not confuse this function with the `require('ipfs-repo-migrations').revert()` function that drives the whole backward migration process!_
 
@@ -140,7 +191,7 @@ Arguments:
  * `options` (object, optional) - object containing `IPFSRepo` options, that should be used to construct the datastore instance.
  * `isBrowser` (bool) - indicates if the migration is run in a browser environment (as opposed to NodeJS)
 
-#### Browser vs. NodeJS environments
+### Browser vs. NodeJS environments
 
 The migration might need to distinguish in which environment it runs (browser vs. NodeJS). For this reason there is an argument
 `isBrowser` passed to migrations functions. But with simple migrations it should not be necessary to distinguish between
@@ -157,37 +208,23 @@ There are currently two main datastore implementations:
  So with simple migrations you shouldn't worry about the difference between `datastore-fs` and `datastore-level` 
  and by default use the `datastore-fs` package (as the replace mechanism does not work vice versa).
 
-#### Guidelines
+### Guidelines
 
 The recommended way to write a new migration is to first bootstrap a dummy migration using the CLI:
 
 ```sh
-> jsipfs-migrations add
+> npm run new-migration
 ```
 
 A new folder is created with the bootstrapped migration. You can then simply fill in the required fields and 
 write the rest of the migration! 
 
-#### Migration's dependencies
-
-The size of the `js-ipfs` bundle is crucial for distribution in a browser environment, so dependency management of all related
-packages is important.
-
-If a migration needs to depend on some package, this dependency should be declared in the root's `package.json`. The author
-of the migration should be thoughtful about adding dependencies that would significantly increase the size of the final bundle.
-
-Most of the migration's dependencies will most likely overlap with `js-ipfs`'s dependencies and hence should not introduce
-any significant overhead, but it is necessary to keep the versions of these dependencies in sync with `js-ipfs`. For this 
-reason migrations should be well tested to ensure correct behaviour over dependency updates.
-An update of some dependency could introduce breaking change. In such a case the next steps should be discussed with a broader 
-audience. 
-
-#### Integration with js-ipfs
+### Integration with js-ipfs
 
 When a new migration is created, the repo version in [`js-ipfs-repo`](https://github.com/ipfs/js-ipfs-repo) should be updated with the new version,
 together with updated version of this package. Then the updated version should be propagated to `js-ipfs`.
 
-#### Tests
+### Tests
 
 If a migration affects any of the following functionality, it must provide tests for the following functions
  to work under the version of the repo that it migrates to:
@@ -199,15 +236,15 @@ If a migration affects any of the following functionality, it must provide tests
 Every migration must have test coverage. Tests for migrations should be placed in the `/test/migrations/` folder. Most probably
 you will have to plug the tests into `browser.js`/`node.js` if they require specific bootstrapping on each platform.
 
-#### Empty migrations
+### Empty migrations
 
 For interop with go-ipfs it might be necessary just to bump a version of a repo without any actual 
 modification as there might not be any changes needed in the JS implementation. For that purpose you can create an "empty migration".
 
 The easiest way to do so is with the CLI:
 
 ```sh
-> jsipfs-migrations add --empty
+> npm run new-migration -- --empty
 ```
 
 This will create an empty migration with the next version.
@@ -218,62 +255,9 @@ This will create an empty migration with the next version.
 | -----------------: |:----------------:|
 |                  7 | v0.0.0 - latest  |
 
+## Developer
 
-## API
-
-### `migrate(path, {toVersion, ignoreLock, repoOptions, onProgress, isDryRun}) -> Promise<void>`
-
-Executes a forward migration to a specific version, or to the latest version if a specific version is not specified.
-
-**Arguments:**
-
- * `path` (string, mandatory) - path to the repo to be migrated
- * `options` (object, optional) - options for the migration
- * `options.toVersion` (int, optional) - version to which the repo should be migrated. Defaults to the latest migration version.
- * `options.ignoreLock` (bool, optional) - if true will not lock the repo when applying migrations. Use with caution.
- * `options.repoOptions` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
- * `options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
- * `options.isDryRun` (bool, optional) - flag that indicates if it is a dry run that should give the same output as running a migration but without making any actual changes.
- 
-#### `onProgress(migration, counter, totalMigrations)`
- 
-Signature of the progress callback.
-
-**Arguments:**
- * `migration` (object) - object of migration that just successfully finished running. See [Architecture of migrations](#architecture-of-migrations) for details.
- * `counter` (int) - index of current migration.
- * `totalMigrations` (int) - total count of migrations that will be run.
-
-### `revert(path, toVersion, {ignoreLock, options, onProgress, isDryRun}) -> Promise<void>`
-
-Executes backward migration to a specific version.
-
-**Arguments:**
-
- * `path` (string, mandatory) - path to the repo to be reverted
- * `toVersion` (int, mandatory) - version to which the repo should be reverted to. 
- * `options` (object, optional) - options for the reversion
- * `options.ignoreLock` (bool, optional) - if true will not lock the repo when applying migrations. Use with caution.
- * `options.options` (object, optional) - options that are passed to migrations, that use them to construct the datastore. (options are the same as for IPFSRepo).
- * `options.onProgress` (function, optional) - callback that is called after finishing execution of each migration to report progress.
- * `options.isDryRun` (bool, optional) - flag that indicates if it is a dry run that should give the same output as running a migration but without making any actual changes.
- 
-### `getLatestMigrationVersion() -> int`
-
-Return the version of the latest migration.
-
-## CLI
-
-The CLI is a NodeJS binary named `jsipfs-repo-migrations`. 
-It has several commands:
-
- * `migrate` - performs forward/backward migration to specific or latest version.
- * `status` - check repo for migrations that should be run.
- * `add` - bootstraps new migration.
- 
-For further details see the `--help` pages.
-
-## Versioning
+### Module versioning notes 
 
 In order to have good overview of what version of package contains what kind of migrations, this package follows this versioning schema: `0.<versionOfLastMigration>.<patches>`.
 
diff --git a/package.json b/package.json
@@ -32,6 +32,7 @@
     "url": "https://github.com/ipfs/js-ipfs-repo-migrations.git"
   },
   "scripts": {
+    "new-migration": "./src/cli.js add",
     "test": "aegir test",
     "test:node": "aegir test --target node",
     "test:browser": "aegir test --target browser",
