Skip to content

Commit 775476b

Browse files
dgp1130alxhub
dgp1130
authored and
alxhub
committed
docs(devtools): update README to be more clear for extension reviewers (#55406)
Mozilla requires add-ons to have reproducible builds and this is managed directly by human reviewers and need to understand how to build Angular DevTools correctly. This commit defines a reproducible way of building Angular DevTools which is useful for reviewers and contributers. The actual changes I made include: 1. Moving local development content into `devtools/README` (deleting `devtools/DEVELOPING.md`) and explicitly stating the Node version as well as global Yarn install to be clear about the correct way to build the extension. This should make it easier for reviewers to understand and reproduce builds. 2. Moving release instructions to a separate doc to reduce noise as well as making some minor clean ups there. I briefly considered pointing reviewers at a new `devtools/docs/reviewers.md` doc, but decided against it because I want these instructions to be maintained in a single location where contributors and reviewers use the same content. This way any changes don't miss one of these sets of users. If reviewers have trouble with this format (dev builds isn't useful to reviewers and some content is repeated from other docs for contributors) then we can consider splitting out to a separate `reviewers.md` file. But until then, I'd like to try sharing this content and see how it works out in practice. PR Close #55406
1 parent 5cf14da commit 775476b

3 files changed

Lines changed: 153 additions & 113 deletions

File tree

‎devtools/DEVELOPING.md‎

Lines changed: 0 additions & 39 deletions
This file was deleted.

‎devtools/README.md‎

Lines changed: 40 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -2,111 +2,77 @@
22

33
Angular DevTools is a browser DevTools extension for debugging and profiling Angular applications.
44

5-
## Installing and Running locally
5+
## Developing Locally
66

7-
To setup your local development environment for Angular DevTools, see [DEVELOPING.md](./DEVELOPING.md)
7+
<!-- This duplicates some general content for setting up the angular/angular repository, however it is important to
8+
have complete instructions here for Mozilla Add-On reviewers who need to be able to reproduce Angular DevTools
9+
builds and will use the same documentation. -->
810

9-
## Publish Angular DevTools
11+
### Set up
1012

11-
Publishing Angular DevTools is a five step process:
12-
1. Sync and update workspace.
13-
1. Update extension version numbers.
14-
1. Publish to Chrome.
15-
1. Publish to Firefox.
16-
1. Commit and merge the updated version numbers.
13+
Follow the instructions below to set up your Angular DevTools development
14+
environment. Note that all commands should be executed in the repository root, not
15+
`devtools/`. All file paths are also relative to the repository root.
1716

18-
### 1. Sync workspace
17+
Debian Linux, MacOS, and Windows via WSL should build successfully. Building
18+
natively on Windows without WSL is not supported at the moment.
1919

20-
Before starting anything, make sure your workspace is up to date with latest changes and dependencies.
20+
To set up your development environment, first install the [correct version of Node](/.nvmrc). If you have
21+
[`nvm`](https://github.com/nvm-sh/nvm) set up, this can be done with:
2122

2223
```shell
23-
git checkout main
24-
git pull upstream main
2524
nvm install
26-
yarn --frozen-lockfile
2725
```
2826

29-
### 2. Update extension version numbers
30-
31-
Bump the version numbers listed in
32-
[`manifest.chrome.json`](/devtools/projects/shell-browser/src/manifest/manifest.chrome.json)
33-
and [`manifest.firefox.json`](/devtools/projects/shell-browser/src/manifest/manifest.firefox.json).
27+
Second, install [Yarn](https://classic.yarnpkg.com/en/):
3428

35-
### 3. Publish to Chrome Chrome
29+
```shell
30+
npm install -g yarn@1
31+
```
3632

37-
To publish Angular DevTools to the Chrome Web Store, first build and package the extension.
33+
Third, install NPM dependencies:
3834

3935
```shell
40-
# Build the Chrome version.
41-
yarn devtools:build:chrome
42-
43-
# Package the extension.
44-
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-chrome.zip *)
36+
yarn --frozen-lockfile
4537
```
4638

47-
Then upload it to the Chrome Web Store.
39+
Now you should be ready to build the DevTools extension.
4840

49-
1. Go to the extension [page](https://chrome.google.com/webstore/category/extensions)
50-
1. Make sure your email is part of the Google Group we use for publishing the extension
51-
1. Navigate to "Developer Dashboard"
52-
1. Enter your account credentials
53-
1. You should be able to change the publisher to "Angular"
41+
### Dev builds
5442

55-
You can choose to either publish immediately or only get approval but hold to publish at a later time.
56-
Note that even publishing immediately still requires approval from Chrome Web Store before it is
57-
available to users. Historically this has been pretty quick (< 30 minutes), but there is no hard upper
58-
limit on how long a review might take: https://developer.chrome.com/docs/webstore/review-process#review-time.
43+
To run the extension in development mode run:
5944

60-
### 4. Firefox
45+
```shell
46+
yarn devtools:devserver
47+
```
6148

62-
To publish Angular DevTools as a Firefox Add-on, first build and package the extension.
49+
You can also run a standalone version of the demo app with:
6350

6451
```shell
65-
# Build the Firefox version.
66-
yarn devtools:build:firefox
67-
68-
# Package the extension.
69-
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-firefox.zip *)
52+
yarn devtools:devserver:demo-standalone
7053
```
7154

72-
Then upload it:
55+
This would start a development server that you can access on <http://localhost:4200>. In development, Angular DevTools
56+
uses a "development shell." This is different from "chrome shell" in a way, that it runs the user's app in an iframe.
57+
DevTools then communicate with the user's app via message passing.
7358

74-
1. Go to the Firefox Addons [page](https://addons.mozilla.org/developers/addons)
75-
1. For email enter `[email protected]`
76-
1. Find the password [on Valentine](http://valentine/#/show/1651707871496288)
77-
1. Setup Google Authenticator with the 2FA QR code. You can find the QR code on Valentine
59+
### Release builds
7860

79-
The Firefox publishing process is slightly more involved than Chrome. In particular, they
80-
require extension source code with instructions to build and run it. Since DevTools exists in
81-
a monorepo with critical build tooling existing outside the `devtools/` directory, we need to
82-
upload the entire monorepo. Package it without dependencies and generated files with the
83-
following command and upload it.
61+
You can build the release version of Angular DevTools for either Chrome or Firefox with:
8462

8563
```shell
86-
zip -r ~/angular-source.zip * -x ".git/*" -x "node_modules/*" -x "**/node_modules/*" -x "dist/"
64+
yarn devtools:build:chrome
65+
yarn devtools:build:firefox
8766
```
8867

89-
Suggested note to reviewer:
68+
Either way, the built extension will be at `dist/bin/devtools/projects/shell-browser/src/prodapp`.
9069

91-
> This is a monorepo and includes much more code than just the DevTools extension. The relevant
92-
> code is under `devtools/...` and `devtools/README.md` contains instructions for building and
93-
> testing locally.
94-
>
95-
> The uploaded source is equivalent to
96-
> https://github.com/angular/angular/tree/${permalink to current main}/ with the single change
97-
> of a bumped version number in the `manifest.json` file.
70+
#### Installation
9871

99-
### 5. Commit and merge
100-
101-
Commit the version bump:
102-
103-
```shell
104-
git checkout -b devtools-release
105-
git add . && git commit -m "release: bump Angular DevTools version to 1.0.10"
106-
git push -u origin devtools-release
107-
```
72+
For Chrome, you can install the extension from `dist/bin/devtools/projects/shell-browser/src/prodapp` by following the
73+
guide from [here](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world#load-unpacked).
10874

109-
Then create and merge a PR targeting `patch` with this change.
75+
For Firefox, to load the extension, you can go to the about:debugging page, click the "This Firefox" option and then
76+
click the Load Temporary Add-on button. You'll have to select the manifest file in
77+
`dist/bin/devtools/projects/shell-browser/src/prodapp` directly.
11078

111-
Once the PR merges and both Chrome and Firefox are showing the new version to end users, then
112-
the release is complete!

‎devtools/docs/release.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Publish Angular DevTools
2+
3+
Publishing Angular DevTools is a five step process:
4+
1. Sync and update workspace.
5+
1. Update extension version numbers.
6+
1. Publish to Chrome.
7+
1. Publish to Firefox.
8+
1. Commit and merge the updated version numbers.
9+
10+
## 1. Sync workspace
11+
12+
Before starting anything, make sure your workspace is up to date with latest changes and dependencies.
13+
14+
```shell
15+
git checkout main
16+
git pull upstream main
17+
nvm install
18+
yarn --frozen-lockfile
19+
```
20+
21+
## 2. Update extension version numbers
22+
23+
Bump the version numbers listed in
24+
[`manifest.chrome.json`](/devtools/projects/shell-browser/src/manifest/manifest.chrome.json)
25+
and [`manifest.firefox.json`](/devtools/projects/shell-browser/src/manifest/manifest.firefox.json).
26+
27+
## 3. Publish to Chrome Chrome
28+
29+
To publish Angular DevTools to the Chrome Web Store, first build and package the extension.
30+
31+
```shell
32+
# Build the Chrome version.
33+
yarn devtools:build:chrome
34+
35+
# Package the extension.
36+
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-chrome.zip *)
37+
```
38+
39+
Then upload it to the Chrome Web Store.
40+
41+
1. Go to the extension [page](https://chrome.google.com/webstore/category/extensions)
42+
1. Make sure your email is part of the Google Group we use for publishing the extension
43+
1. Navigate to "Developer Dashboard"
44+
1. Enter your account credentials
45+
1. You should be able to change the publisher to "Angular"
46+
47+
You can choose to either publish immediately or only get approval but hold to publish at a later time.
48+
Note that even publishing immediately still requires approval from Chrome Web Store before it is
49+
available to users. Historically this has been pretty quick (< 30 minutes), but there is no hard upper
50+
limit on how long a review might take: https://developer.chrome.com/docs/webstore/review-process#review-time.
51+
52+
## 4. Publish to Firefox
53+
54+
To publish Angular DevTools as a Firefox Add-on, first build and package the extension.
55+
56+
```shell
57+
# Build the Firefox version.
58+
yarn devtools:build:firefox
59+
60+
# Package the extension.
61+
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-firefox.zip *)
62+
```
63+
64+
Then upload it:
65+
66+
1. Go to the Firefox Addons [page](https://addons.mozilla.org/developers/addons)
67+
1. Find the email and password [on Valentine](http://valentine/#/show/1651707871496288)
68+
1. Setup Google Authenticator with the 2FA QR code.
69+
* You can find the QR code [on Valentine as well](http://valentine/#/show/1651792043556329)
70+
71+
The Firefox publishing process is slightly more involved than Chrome. In particular, they
72+
require extension source code with instructions to build and run it. Since DevTools exists in
73+
a monorepo with critical build tooling existing outside the `devtools/` directory, we need to
74+
upload the entire monorepo. Package it without dependencies and generated files with the
75+
following command and upload it.
76+
77+
```shell
78+
zip -r ~/angular-source.zip * -x ".git/*" -x "node_modules/*" -x "**/node_modules/*" -x "dist/"
79+
```
80+
81+
Suggested note to reviewer:
82+
83+
> This is a monorepo and includes much more code than just the DevTools extension. The relevant
84+
> code is under `devtools/...` and `devtools/README.md` contains instructions for compiling release
85+
> builds locally.
86+
>
87+
> The uploaded source is equivalent to
88+
> https://github.com/angular/angular/tree/${permalink to current main}/ with the single change
89+
> of a bumped version number in the `manifest.json` file.
90+
91+
### 5. Commit and merge
92+
93+
Commit the version bump:
94+
95+
```shell
96+
git checkout -b devtools-release
97+
git add . && git commit -m "release: bump Angular DevTools version to 1.0.10"
98+
git push -u origin devtools-release
99+
```
100+
101+
Then create and merge a PR targeting `patch` with this change.
102+
103+
Once the PR merges and both Chrome and Firefox are showing the new version to end users, then
104+
the release is complete!
105+
106+
git add . && git commit -m "release: bump Angular DevTools version to 1.0.10"
107+
git push -u origin devtools-release
108+
```
109+
110+
Then create and merge a PR targeting `patch` with this change.
111+
112+
Once the PR merges and both Chrome and Firefox are showing the new version to end users, then
113+
the release is complete!

0 commit comments

Comments
 (0)