diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.md | 1 | ||||
| -rw-r--r-- | docs/architecture.png | bin | 140227 -> 218930 bytes | |||
| -rw-r--r-- | docs/bumping_version.md | 4 | ||||
| -rw-r--r-- | docs/components/account-menu.md | 20 | ||||
| -rw-r--r-- | docs/developing-on-deps.md | 8 | ||||
| -rw-r--r-- | docs/notices.md | 15 | ||||
| -rw-r--r-- | docs/porting_to_new_environment.md | 38 | ||||
| -rw-r--r-- | docs/publishing.md | 6 | ||||
| -rw-r--r-- | docs/sensitive-release.md | 5 | ||||
| -rw-r--r-- | docs/transaction-flow.png | bin | 141125 -> 93568 bytes |
10 files changed, 67 insertions, 30 deletions
diff --git a/docs/README.md b/docs/README.md index 3c9bc0b4a..6c54c98cf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,6 @@ To learn how to develop MetaMask-compatible applications, visit our [Developer D - [Publishing Guide](./publishing.md) - [How to live reload on local dependency changes](./developing-on-deps.md) - [How to add new networks to the Provider Menu](./adding-new-networks.md) -- [How to manage notices that appear when the app starts up](./notices.md) - [How to port MetaMask to a new platform](./porting_to_new_environment.md) - [How to generate a visualization of this repository's development](./development-visualization.md) - [How to add a feature behind a secret feature flag](./secret-preferences.md) diff --git a/docs/architecture.png b/docs/architecture.png Binary files differindex 2a5924827..d173c651a 100644 --- a/docs/architecture.png +++ b/docs/architecture.png diff --git a/docs/bumping_version.md b/docs/bumping_version.md index df38369a2..5b4ca40a6 100644 --- a/docs/bumping_version.md +++ b/docs/bumping_version.md @@ -1,7 +1,7 @@ # How to Bump MetaMask's Version Automatically ``` -npm run version:bump patch +yarn version:bump patch ``` MetaMask publishes using a loose [semver](https://semver.org/) interpretation. We divide the three segments of our version into three types of version bump: @@ -20,7 +20,7 @@ Means a fix for a bug, or correcting something that should have been assumed to # Bumping the version -`npm run version:bump $BUMP_TYPE` where `$BUMP_TYPE` is one of `major`, `minor`, or `patch`. +`yarn version:bump $BUMP_TYPE` where `$BUMP_TYPE` is one of `major`, `minor`, or `patch`. This will increment the version in the `app/manifest.json` and `CHANGELOG.md` files according to our current protocol, where the manifest's version is updated, and any line items currently under the changelog's "master" section are now under the new dated version section. diff --git a/docs/components/account-menu.md b/docs/components/account-menu.md new file mode 100644 index 000000000..464616b75 --- /dev/null +++ b/docs/components/account-menu.md @@ -0,0 +1,20 @@ +# Account Menu + +The account menu is the popup menu which contains options such as: + - Logging out + - Switching accounts + - Creating a new account + - Importing an account + - Connecting a HW wallet + - Looking up info & help + - Adjusting settings + + It can be seen below where it has been outlined with a red box + +  + + Above screenshot showing the menu bar in MetaMask 6.7.1 + + + + diff --git a/docs/developing-on-deps.md b/docs/developing-on-deps.md index e2e07cb4e..20c0f7c97 100644 --- a/docs/developing-on-deps.md +++ b/docs/developing-on-deps.md @@ -3,7 +3,7 @@ To enjoy the live-reloading that `gulp dev` offers while working on the dependencies: 1. Clone the dependency locally. - 2. `npm install` in its folder. - 3. Run `npm link` in its folder. - 4. Run `npm link $DEP_NAME` in this project folder. - 5. Next time you `npm start` it will watch the dependency for changes as well! + 2. `npm install` or `yarn install` in its folder. + 3. Run `yarn link` in its folder. + 4. Run `yarn link $DEP_NAME` in this project folder. + 5. Next time you `yarn start` it will watch the dependency for changes as well! diff --git a/docs/notices.md b/docs/notices.md deleted file mode 100644 index 826e6e84e..000000000 --- a/docs/notices.md +++ /dev/null @@ -1,15 +0,0 @@ -## Generating Notices - -To add a notice: -``` -npm run generateNotice -``` -Enter the body of your notice into the text editor that pops up, without including the body. Be sure to save the file before closing the window! -Afterwards, enter the title of the notice in the command line and press enter. Afterwards, add and commit the new changes made. - -To delete a notice: -``` -npm run deleteNotice -``` -A list of active notices will pop up. Enter the corresponding id in the command line prompt and add and commit the new changes afterwards. - diff --git a/docs/porting_to_new_environment.md b/docs/porting_to_new_environment.md index f7a2ac8b7..9cb8e9c2d 100644 --- a/docs/porting_to_new_environment.md +++ b/docs/porting_to_new_environment.md @@ -10,6 +10,41 @@ The `metamask-background` describes the file at `app/scripts/background.js`, whi When a new site is visited, the WebExtension creates a new `ContentScript` in that page's context, which can be seen at `app/scripts/contentscript.js`. This script represents a per-page setup process, which creates the per-page `web3` api, connects it to the background script via the Port API (wrapped in a [stream abstraction](https://github.com/substack/stream-handbook)), and injected into the DOM before anything loads. +You can choose to use this streaming interface to connect to the MetaMask controller over any transport you can wrap with a stream, by connecting it to the [metamask-inpage-provider](https://github.com/MetaMask/metamask-inpage-provider), but you can also construct a provider per domain like this: + +```javascript +const providerFromEngine = require('eth-json-rpc-middleware/providerFromEngine') + +/** +* returns a provider restricted to the requesting domain +**/ +function incomingConnection (domain, getSiteMetadata) { + const engine = metamaskController.setupProviderEngine(domain, getSiteMetadata) + const provider = providerFromEngine(engine) + return provider +} +``` + +Please note if you take this approach, you are responsible for cleaning up the filters when the page is closed: + +``` +const filterMiddleware = engine._middleware.filter(mid => mid.name === 'filterMiddleware')[0] +filterMiddleware.destroy() +``` + +### getSiteMetadata() + +This method is used to enhance our confirmation screens with images and text representing the requesting domain. + +It should return a promise that resolves with an object with the following properties: + +- `name`: The requesting site's name. +- `icon`: A URI representing the site's logo. + +### Using the Streams Interface + +Only use this if you intend to construct the [metamask-inpage-provider](https://github.com/MetaMask/metamask-inpage-provider) over a stream! + The most confusing part about porting MetaMask to a new platform is the way we provide the Web3 API over a series of streams between contexts. Once you understand how we create the [MetamaskInpageProvider](https://github.com/MetaMask/metamask-inpage-provider/blob/master/index.js) in the [inpage.js script](../app/scripts/inpage.js), you will be able to understand how the [port-stream](../app/scripts/lib/port-stream.js) is just a thin wrapper around the [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage), and a similar stream API can be wrapped around any communication channel to communicate with the `MetaMaskController` via its `setupUntrustedCommunication(stream, domain)` method. ### The MetaMask Controller @@ -52,7 +87,7 @@ Returns a JavaScript object filled with callback functions representing every op The MetaMask UI is essentially just a website that can be configured by passing it the API and state subscriptions from above. Anyone could make a UI that consumes these, effectively reskinning MetaMask. -You can see this in action in our file [ui/index.js](https://github.com/MetaMask/metamask-extension/blob/master/ui/index.js). There you can see an argument being passed in named `accountManager`, which is essentially a MetaMask controller (forgive its really outdated parameter name!). With access to that object, the UI is able to initialize a whole React/Redux app that relies on this API for its account/blockchain-related/persistent states. +You can see this in action in our file [ui/index.js](https://github.com/MetaMask/metamask-extension/blob/master/ui/index.js). There you can see the background connection being passed in, which is essentially the MetaMask controller. With access to that object, the UI is able to initialize a whole React/Redux app that relies on this API for its account/blockchain-related/persistent states. ## Putting it Together @@ -64,7 +99,6 @@ In that file, there's a lot going on, so it's maybe worth focusing on our MetaMa const controller = new MetamaskController({ // User confirmation callbacks: showUnconfirmedMessage: triggerUi, - unlockAccountMessage: triggerUi, showUnapprovedTx: triggerUi, // initial state initState, diff --git a/docs/publishing.md b/docs/publishing.md index 8d50e6869..17192ee8a 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -20,9 +20,9 @@ We try to ensure certain criteria are met before deploying: ## Incrementing Version & Changelog -Version can be automatically incremented [using our bump script](./bumping-version.md). +Version can be automatically incremented by creating a branch with the name `Version-vX.Y.Z`, where `X`, `Y`, and `Z` are numbers. Branches should be created off of the main branch. [Branches can be created on GitHub.](https://help.github.com/en/articles/creating-and-deleting-branches-within-your-repository) -npm run version:bump `$BUMP_TYPE` where `$BUMP_TYPE` is one of `major`, `minor`, or `patch`. +Once a version branch has been created, a build on CircleCI will create a Pull Request for the release with the app manifest and changelog versions bumped. ## Preparing for Sensitive Changes @@ -41,7 +41,7 @@ With each pull request, the @MetaMaskBot will comment with a build of that new p 3. Publish to [firefox addon marketplace](http://addons.mozilla.org/en-us/firefox/addon/ether-metamask). 4. Publish to [Opera store](https://addons.opera.com/en/extensions/details/metamask/). 5. Post on [Github releases](https://github.com/MetaMask/metamask-extension/releases) page. -6. Run the `npm run announce` script, and post that announcement in our public places. +6. Run the `yarn announce` script, and post that announcement in our public places. ## Hotfix Differences diff --git a/docs/sensitive-release.md b/docs/sensitive-release.md index 288df57eb..1ebae3932 100644 --- a/docs/sensitive-release.md +++ b/docs/sensitive-release.md @@ -18,10 +18,9 @@ Simply follow the steps in [the publishing guide](./publishing.md). ### Prepare Rollback Release -1. Be on the new risky version branch. -2. Run `npm run rollback $ROLLBACK_TARGET_VERSION`. +Follow the steps in [the publishing guide](./publishing.md) with a different context: -The rollback version will now be a branch and tag on the origin. +Instead of creating a version branch off of the main branch, create a version branch off of the latest release. It is customary that this release increments the patch version number. ### Roll the normal release out diff --git a/docs/transaction-flow.png b/docs/transaction-flow.png Binary files differindex 1059b60d8..d86965a14 100644 --- a/docs/transaction-flow.png +++ b/docs/transaction-flow.png |
