Skip to content

Commit d0144c2

Browse files
danfinlaydanfinlay
committed
Break docs up into individual files
1 parent 7f991e5 commit d0144c2

10 files changed

+153
-151
lines changed

‎README.md

Lines changed: 17 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,15 @@ If you're a web dapp developer, we've got two types of guides for you:
1818

1919
Uncompressed builds can be found in `/dist`, compressed builds can be found in `/builds` once they're built.
2020

21-
## Installing Local Builds on Chrome
21+
### Running Tests
2222

23-
To install your locally built extension on Chrome, [follow this guide](http://stackoverflow.com/a/24577660/272576).
23+
Requires `mocha` installed. Run `npm install -g mocha`.
2424

25-
The built extension is stored in `./dist/chrome/`.
25+
Then just run `npm test`.
26+
27+
You can also test with a continuously watching process, via `npm run watch`.
28+
29+
You can run the linter by itself with `gulp lint`.
2630

2731
## Architecture
2832

@@ -41,160 +45,22 @@ npm start
4145
npm run dist
4246
```
4347

44-
#### In Chrome
45-
46-
Open `Settings` > `Extensions`.
47-
48-
Check "Developer mode".
49-
50-
At the top, click `Load Unpacked Extension`.
51-
52-
Navigate to your `metamask-plugin/dist/chrome` folder.
53-
54-
Click `Select`.
55-
56-
You now have the plugin, and can click 'inspect views: background plugin' to view its dev console.
57-
58-
#### In Firefox
59-
60-
Go to the url `about:debugging`.
61-
62-
Click the button `Load Temporary Add-On`.
63-
64-
Select the file `dist/firefox/manifest.json`.
65-
66-
You can optionally enable debugging, and click `Debug`, for a console window that logs all of Metamask's processes to a single console.
67-
68-
If you have problems debugging, try connecting to the IRC channel `#webextensions` on `irc.mozilla.org`.
69-
70-
For longer questions, use the StackOverfow tag `firefox-addons`.
71-
72-
### Developing on UI Only
73-
74-
You can run `npm run ui`, and your browser should open a live-reloading demo version of the plugin UI.
75-
76-
Some actions will crash the app, so this is only for tuning aesthetics, but it allows live-reloading styles, which is a much faster feedback loop than reloading the full extension.
77-
78-
### Developing on UI with Mocked Background Process
79-
80-
You can run `npm run mock` and your browser should open a live-reloading demo version of the plugin UI, just like the `npm run ui`, except that it tries to actually perform all normal operations.
81-
82-
It does not yet connect to a real blockchain (this could be a good test feature later, connecting to a test blockchain), so only local operations work.
83-
84-
You can reset the mock ui at any time with the `Reset` button at the top of the screen.
85-
86-
### Developing on Dependencies
87-
88-
To enjoy the live-reloading that `gulp dev` offers while working on the `web3-provider-engine` or other dependencies:
89-
90-
1. Clone the dependency locally.
91-
2. `npm install` in its folder.
92-
3. Run `npm link` in its folder.
93-
4. Run `npm link $DEP_NAME` in this project folder.
94-
5. Next time you `npm start` it will watch the dependency for changes as well!
95-
96-
### Running Tests
97-
98-
Requires `mocha` installed. Run `npm install -g mocha`.
99-
100-
Then just run `npm test`.
101-
102-
You can also test with a continuously watching process, via `npm run watch`.
103-
104-
You can run the linter by itself with `gulp lint`.
105-
10648
#### Writing Browser Tests
10749

10850
To write tests that will be run in the browser using QUnit, add your test files to `test/integration/lib`.
10951

110-
### Deploying the UI
52+
## Other Docs
11153

112-
You must be authorized already on the MetaMask plugin.
113-
114-
0. Update the version in `app/manifest.json` and the Changelog in `CHANGELOG.md`.
115-
1. Visit [the chrome developer dashboard](https://chrome.google.com/webstore/developer/dashboard?authuser=2).
116-
2. Run `gulp dist` (or `gulp zip` if you've already built)
117-
3. Upload the latest zip file from `builds/metamask-$PLATFORM-$VERSION.zip` as the updated package.
54+
- [How to add custom build to Chrome](./docs/add-to-chrome.md)
55+
- [How to add custom build to Firefox](./docs/add-to-firefox.md)
56+
- [How to develop a live-reloading UI](./docs/ui-dev-mode.md)
57+
- [Publishing Guide](./docs/publishing.md)
58+
- [How to develop an in-browser mocked UI](./docs/ui-mock-mode.md)
59+
- [How to live reload on local dependency changes](./docs/developing-on-deps.md)
60+
- [How to add new networks to the Provider Menu](./docs/adding-new-networks.md)
61+
- [How to manage notices that appear when the app starts up](./docs/notices.md)
62+
- [How to generate a visualization of this repository's development](./docs/development-visualization.md)
11863

11964
[1]: http://www.nomnoml.com/#view/%5B%3Cactor%3Euser%5D%0A%0A%5Bmetamask-ui%7C%0A%20%20%20%5Btools%7C%0A%20%20%20%20%20react%0A%20%20%20%20%20redux%0A%20%20%20%20%20thunk%0A%20%20%20%20%20ethUtils%0A%20%20%20%20%20jazzicon%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20account-detail%0A%20%20%20%20%20accounts%0A%20%20%20%20%20locked-screen%0A%20%20%20%20%20restore-vault%0A%20%20%20%20%20identicon%0A%20%20%20%20%20config%0A%20%20%20%20%20info%0A%20%20%20%5D%0A%20%20%20%5Breducers%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20metamask%0A%20%20%20%20%20identities%0A%20%20%20%5D%0A%20%20%20%5Bactions%7C%0A%20%20%20%20%20%5BaccountManager%5D%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%5D%3A-%3E%5Bactions%5D%0A%20%20%20%5Bactions%5D%3A-%3E%5Breducers%5D%0A%20%20%20%5Breducers%5D%3A-%3E%5Bcomponents%5D%0A%5D%0A%0A%5Bweb%20dapp%7C%0A%20%20%5Bui%20code%5D%0A%20%20%5Bweb3%5D%0A%20%20%5Bmetamask-inpage%5D%0A%20%20%0A%20%20%5B%3Cactor%3Eui%20developer%5D%0A%20%20%5Bui%20developer%5D-%3E%5Bui%20code%5D%0A%20%20%5Bui%20code%5D%3C-%3E%5Bweb3%5D%0A%20%20%5Bweb3%5D%3C-%3E%5Bmetamask-inpage%5D%0A%5D%0A%0A%5Bmetamask-background%7C%0A%20%20%5Bprovider-engine%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bid%20store%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%3E%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%3C-%3E%5Bid%20store%5D%0A%20%20%5Bconfig%20manager%7C%0A%20%20%20%20%5Brpc%20configuration%5D%0A%20%20%20%20%5Bencrypted%20keys%5D%0A%20%20%20%20%5Bwallet%20nicknames%5D%0A%20%20%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%5Bconfig%20manager%5D%0A%20%20%5Bid%20store%5D%3C-%3E%5Bconfig%20manager%5D%0A%5D%0A%0A%5Buser%5D%3C-%3E%5Bmetamask-ui%5D%0A%0A%5Buser%5D%3C%3A--%3A%3E%5Bweb%20dapp%5D%0A%0A%5Bmetamask-contentscript%7C%0A%20%20%5Bplugin%20restart%20detector%5D%0A%20%20%5Brpc%20passthrough%5D%0A%5D%0A%0A%5Brpc%20%7C%0A%20%20%5Bethereum%20blockchain%20%7C%0A%20%20%20%20%5Bcontracts%5D%0A%20%20%20%20%5Baccounts%5D%0A%20%20%5D%0A%5D%0A%0A%5Bweb%20dapp%5D%3C%3A--%3A%3E%5Bmetamask-contentscript%5D%0A%5Bmetamask-contentscript%5D%3C-%3E%5Bmetamask-background%5D%0A%5Bmetamask-background%5D%3C-%3E%5Bmetamask-ui%5D%0A%5Bmetamask-background%5D%3C-%3E%5Brpc%5D%0A
12065

12166

122-
### Generate Development Visualization
123-
124-
This will generate a video of the repo commit history.
125-
126-
Install preqs:
127-
```
128-
brew install gource
129-
brew install ffmpeg
130-
```
131-
132-
From the repo dir, pipe `gource` into `ffmpeg`:
133-
```
134-
gource \
135-
--seconds-per-day .1 \
136-
--user-scale 1.5 \
137-
--default-user-image "./images/icon-512.png" \
138-
--viewport 1280x720 \
139-
--auto-skip-seconds .1 \
140-
--multi-sampling \
141-
--stop-at-end \
142-
--highlight-users \
143-
--hide mouse,progress \
144-
--file-idle-time 0 \
145-
--max-files 0 \
146-
--background-colour 000000 \
147-
--font-size 18 \
148-
--date-format "%b %d, %Y" \
149-
--highlight-dirs \
150-
--user-friction 0.1 \
151-
--title "MetaMask Development History" \
152-
--output-ppm-stream - \
153-
--output-framerate 30 \
154-
| ffmpeg -y -r 30 -f image2pipe -vcodec ppm -i - -b 65536K metamask-dev-history.mp4
155-
```
156-
157-
## Generating Notices
158-
159-
To add a notice:
160-
```
161-
npm run generateNotice
162-
```
163-
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!
164-
Afterwards, enter the title of the notice in the command line and press enter. Afterwards, add and commit the new changes made.
165-
166-
To delete a notice:
167-
```
168-
npm run deleteNotice
169-
```
170-
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.
171-
172-
## Adding Custom Networks
173-
174-
To add another network to our dropdown menu, make sure the following files are adjusted properly:
175-
176-
```
177-
app/scripts/config.js
178-
app/scripts/lib/buy-eth-url.js
179-
app/scripts/lib/config-manager.js
180-
ui/app/app.js
181-
ui/app/components/buy-button-subview.js
182-
ui/app/components/drop-menu-item.js
183-
ui/app/components/network.js
184-
ui/app/components/transaction-list-item.js
185-
ui/app/config.js
186-
ui/app/css/lib.css
187-
ui/lib/account-link.js
188-
ui/lib/explorer-link.js
189-
```
190-
191-
You will need:
192-
+ The network ID
193-
+ An RPC Endpoint url
194-
+ An explorer link
195-
+ CSS for the display icon
196-
197-
## Other Guides
198-
199-
- [Publishing Guide](./docs/publishing.md)
200-

‎docs/add-to-chrome.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## Add Custom Build to Chrome
2+
3+
Open `Settings` > `Extensions`.
4+
5+
Check "Developer mode".
6+
7+
At the top, click `Load Unpacked Extension`.
8+
9+
Navigate to your `metamask-plugin/dist/chrome` folder.
10+
11+
Click `Select`.
12+
13+
You now have the plugin, and can click 'inspect views: background plugin' to view its dev console.
14+

‎docs/add-to-firef.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Add Custom Build to Firefox
2+
3+
Go to the url `about:debugging`.
4+
5+
Click the button `Load Temporary Add-On`.
6+
7+
Select the file `dist/firefox/manifest.json`.
8+
9+
You can optionally enable debugging, and click `Debug`, for a console window that logs all of Metamask's processes to a single console.
10+
11+
If you have problems debugging, try connecting to the IRC channel `#webextensions` on `irc.mozilla.org`.
12+
13+
For longer questions, use the StackOverfow tag `firefox-addons`.
14+

‎docs/adding-new-networks.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
## Adding Custom Networks
2+
3+
To add another network to our dropdown menu, make sure the following files are adjusted properly:
4+
5+
```
6+
app/scripts/config.js
7+
app/scripts/lib/buy-eth-url.js
8+
app/scripts/lib/config-manager.js
9+
ui/app/app.js
10+
ui/app/components/buy-button-subview.js
11+
ui/app/components/drop-menu-item.js
12+
ui/app/components/network.js
13+
ui/app/components/transaction-list-item.js
14+
ui/app/config.js
15+
ui/app/css/lib.css
16+
ui/lib/account-link.js
17+
ui/lib/explorer-link.js
18+
```
19+
20+
You will need:
21+
+ The network ID
22+
+ An RPC Endpoint url
23+
+ An explorer link
24+
+ CSS for the display icon
25+

‎docs/developing-on-deps.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### Developing on Dependencies
2+
3+
To enjoy the live-reloading that `gulp dev` offers while working on the `web3-provider-engine` or other dependencies:
4+
5+
1. Clone the dependency locally.
6+
2. `npm install` in its folder.
7+
3. Run `npm link` in its folder.
8+
4. Run `npm link $DEP_NAME` in this project folder.
9+
5. Next time you `npm start` it will watch the dependency for changes as well!
10+

‎docs/development-visualization.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
### Generate Development Visualization
2+
3+
This will generate a video of the repo commit history.
4+
5+
Install preqs:
6+
```
7+
brew install gource
8+
brew install ffmpeg
9+
```
10+
11+
From the repo dir, pipe `gource` into `ffmpeg`:
12+
```
13+
gource \
14+
--seconds-per-day .1 \
15+
--user-scale 1.5 \
16+
--default-user-image "./images/icon-512.png" \
17+
--viewport 1280x720 \
18+
--auto-skip-seconds .1 \
19+
--multi-sampling \
20+
--stop-at-end \
21+
--highlight-users \
22+
--hide mouse,progress \
23+
--file-idle-time 0 \
24+
--max-files 0 \
25+
--background-colour 000000 \
26+
--font-size 18 \
27+
--date-format "%b %d, %Y" \
28+
--highlight-dirs \
29+
--user-friction 0.1 \
30+
--title "MetaMask Development History" \
31+
--output-ppm-stream - \
32+
--output-framerate 30 \
33+
| ffmpeg -y -r 30 -f image2pipe -vcodec ppm -i - -b 65536K metamask-dev-history.mp4
34+
```
35+

‎docs/notices.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
## Generating Notices
2+
3+
To add a notice:
4+
```
5+
npm run generateNotice
6+
```
7+
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!
8+
Afterwards, enter the title of the notice in the command line and press enter. Afterwards, add and commit the new changes made.
9+
10+
To delete a notice:
11+
```
12+
npm run deleteNotice
13+
```
14+
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.
15+

‎docs/publishing.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22

33
When publishing a new version of MetaMask, we follow this procedure:
44

5+
## Incrementing Version & Changelog
6+
7+
You must be authorized already on the MetaMask plugin.
8+
9+
1. Update the version in `app/manifest.json` and the Changelog in `CHANGELOG.md`.
10+
2. Visit [the chrome developer dashboard](https://chrome.google.com/webstore/developer/dashboard?authuser=2).
11+
12+
## Publishing
13+
514
1. `npm run dist` to generate the latest build.
615
2. Publish to chrome store.
716
3. Publish to firefox addon marketplace.

‎docs/ui-dev-mode.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Running UI Dev Mode
2+
3+
You can run `npm run ui`, and your browser should open a live-reloading demo version of the plugin UI.
4+
5+
Some actions will crash the app, so this is only for tuning aesthetics, but it allows live-reloading styles, which is a much faster feedback loop than reloading the full extension.
6+

‎docs/ui-mock-mode.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
### Developing on UI with Mocked Background Process
2+
3+
You can run `npm run mock` and your browser should open a live-reloading demo version of the plugin UI, just like the `npm run ui`, except that it tries to actually perform all normal operations.
4+
5+
It does not yet connect to a real blockchain (this could be a good test feature later, connecting to a test blockchain), so only local operations work.
6+
7+
You can reset the mock ui at any time with the `Reset` button at the top of the screen.
8+

0 commit comments

Comments
 (0)