skills/angular__angular
1
0
Fork 0
mirror of https://github.com/angular/angular.git synced 2026-09-14 13:54:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(devtools): update README to be more clear for extension reviewers (#55406)

Browse Source 
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
This commit is contained in:
Doug Parker
2024-04-18 12:29:11 -07:00
committed by Alex Rickabaugh
parent 8dab93fe2c
commit d2d275a275
3 changed files with 164 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
devtools/DEVELOPING.md
-39
View File
@@ -1,39 +0,0 @@
# Developing
To setup your development environment run:
```
git clone git@github.com:angular/angular
yarn
```
To run the extension in development mode run:
```
yarn devtools:devserver
```
You can also run a standalone version of the demo app with
```
yarn devtools:devserver:demo-standalone
```
This would start a development server that you can access on <http://localhost:4200>. In development, Angular DevTools uses a "development shell." This is different from "chrome shell" in a way, that it runs the user's app in an iframe. DevTools then communicate with the user's app via message passing.
## Building the extension
To build the Angular DevTools Chrome extension run:
```
yarn devtools:build:chrome
```
You can then install the extension from `dist/bin/devtools/projects/shell-browser/src/prodapp` following the guide from [here](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world#load-unpacked).
You can also build the extension for Firefox with:
```
yarn devtools:build:firefox
```
In Firefox, to load the extension, you can go to the about:debugging page, click the "This Firefox" option and then click the Load Temporary Add-on button. You'll have to select the manifest file in `dist/bin/devtools/projects/shell-browser/src/prodapp` directly.
devtools/README.md
+51 -85
View File
@@ -2,111 +2,77 @@
Angular DevTools is a browser DevTools extension for debugging and profiling Angular applications.
## Installing and Running locally
## Developing Locally
To setup your local development environment for Angular DevTools, see [DEVELOPING.md](./DEVELOPING.md)
<!-- This duplicates some general content for setting up the angular/angular repository, however it is important to
have complete instructions here for Mozilla Add-On reviewers who need to be able to reproduce Angular DevTools
builds and will use the same documentation. -->
## Publish Angular DevTools
### Set up
Publishing Angular DevTools is a five step process:
1. Sync and update workspace.
1. Update extension version numbers.
1. Publish to Chrome.
1. Publish to Firefox.
1. Commit and merge the updated version numbers.
Follow the instructions below to set up your Angular DevTools development
environment. Note that all commands should be executed in the repository root, not
`devtools/`. All file paths are also relative to the repository root.
### 1. Sync workspace
Debian Linux, MacOS, and Windows via WSL should build successfully. Building
natively on Windows without WSL is not supported at the moment.
Before starting anything, make sure your workspace is up to date with latest changes and dependencies.
To set up your development environment, first install the [correct version of Node](/.nvmrc). If you have
[`nvm`](https://github.com/nvm-sh/nvm) set up, this can be done with:
```shell
git checkout main
git pull upstream main
nvm install
```
Second, install [Yarn](https://classic.yarnpkg.com/en/):
```shell
npm install -g yarn@1
```
Third, install NPM dependencies:
```shell
yarn --frozen-lockfile
```
### 2. Update extension version numbers
Now you should be ready to build the DevTools extension.
Bump the version numbers listed in
[`manifest.chrome.json`](/devtools/projects/shell-browser/src/manifest/manifest.chrome.json)
and [`manifest.firefox.json`](/devtools/projects/shell-browser/src/manifest/manifest.firefox.json).
### Dev builds
### 3. Publish to Chrome Chrome
To publish Angular DevTools to the Chrome Web Store, first build and package the extension.
To run the extension in development mode run:
```shell
yarn devtools:devserver
```
You can also run a standalone version of the demo app with:
```shell
yarn devtools:devserver:demo-standalone
```
This would start a development server that you can access on <http://localhost:4200>. In development, Angular DevTools
uses a "development shell." This is different from "chrome shell" in a way, that it runs the user's app in an iframe.
DevTools then communicate with the user's app via message passing.
### Release builds
You can build the release version of Angular DevTools for either Chrome or Firefox with:
```shell
# Build the Chrome version.
yarn devtools:build:chrome
# Package the extension.
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-chrome.zip *)
```
Then upload it to the Chrome Web Store.
1. Go to the extension [page](https://chrome.google.com/webstore/category/extensions)
1. Make sure your email is part of the Google Group we use for publishing the extension
1. Navigate to "Developer Dashboard"
1. Enter your account credentials
1. You should be able to change the publisher to "Angular"
You can choose to either publish immediately or only get approval but hold to publish at a later time.
Note that even publishing immediately still requires approval from Chrome Web Store before it is
available to users. Historically this has been pretty quick (< 30 minutes), but there is no hard upper
limit on how long a review might take: https://developer.chrome.com/docs/webstore/review-process#review-time.
### 4. Firefox
To publish Angular DevTools as a Firefox Add-on, first build and package the extension.
```shell
# Build the Firefox version.
yarn devtools:build:firefox
# Package the extension.
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-firefox.zip *)
```
Then upload it:
Either way, the built extension will be at `dist/bin/devtools/projects/shell-browser/src/prodapp`.
1. Go to the Firefox Addons [page](https://addons.mozilla.org/developers/addons)
1. For email enter `devrel@angular.io`
1. Find the password [on Valentine](http://valentine/#/show/1651707871496288)
1. Setup Google Authenticator with the 2FA QR code. You can find the QR code on Valentine
#### Installation
The Firefox publishing process is slightly more involved than Chrome. In particular, they
require extension source code with instructions to build and run it. Since DevTools exists in
a monorepo with critical build tooling existing outside the `devtools/` directory, we need to
upload the entire monorepo. Package it without dependencies and generated files with the
following command and upload it.
For Chrome, you can install the extension from `dist/bin/devtools/projects/shell-browser/src/prodapp` by following the
guide from [here](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world#load-unpacked).
```shell
zip -r ~/angular-source.zip * -x ".git/*" -x "node_modules/*" -x "**/node_modules/*" -x "dist/"
```
For Firefox, to load the extension, you can go to the about:debugging page, click the "This Firefox" option and then
click the Load Temporary Add-on button. You'll have to select the manifest file in
`dist/bin/devtools/projects/shell-browser/src/prodapp` directly.
Suggested note to reviewer:
> This is a monorepo and includes much more code than just the DevTools extension. The relevant
> code is under `devtools/...` and `devtools/README.md` contains instructions for building and
> testing locally.
>
> The uploaded source is equivalent to
> https://github.com/angular/angular/tree/${permalink to current main}/ with the single change
> of a bumped version number in the `manifest.json` file.
### 5. Commit and merge
Commit the version bump:
```shell
git checkout -b devtools-release
git add . && git commit -m "release: bump Angular DevTools version to 1.0.10"
git push -u origin devtools-release
```
Then create and merge a PR targeting `patch` with this change.
Once the PR merges and both Chrome and Firefox are showing the new version to end users, then
the release is complete!
devtools/docs/release.md
+113
View File
@@ -0,0 +1,113 @@
# Publish Angular DevTools
Publishing Angular DevTools is a five step process:
1. Sync and update workspace.
1. Update extension version numbers.
1. Publish to Chrome.
1. Publish to Firefox.
1. Commit and merge the updated version numbers.
## 1. Sync workspace
Before starting anything, make sure your workspace is up to date with latest changes and dependencies.
```shell
git checkout main
git pull upstream main
nvm install
yarn --frozen-lockfile
```
## 2. Update extension version numbers
Bump the version numbers listed in
[`manifest.chrome.json`](/devtools/projects/shell-browser/src/manifest/manifest.chrome.json)
and [`manifest.firefox.json`](/devtools/projects/shell-browser/src/manifest/manifest.firefox.json).
## 3. Publish to Chrome Chrome
To publish Angular DevTools to the Chrome Web Store, first build and package the extension.
```shell
# Build the Chrome version.
yarn devtools:build:chrome
# Package the extension.
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-chrome.zip *)
```
Then upload it to the Chrome Web Store.
1. Go to the extension [page](https://chrome.google.com/webstore/category/extensions)
1. Make sure your email is part of the Google Group we use for publishing the extension
1. Navigate to "Developer Dashboard"
1. Enter your account credentials
1. You should be able to change the publisher to "Angular"
You can choose to either publish immediately or only get approval but hold to publish at a later time.
Note that even publishing immediately still requires approval from Chrome Web Store before it is
available to users. Historically this has been pretty quick (< 30 minutes), but there is no hard upper
limit on how long a review might take: https://developer.chrome.com/docs/webstore/review-process#review-time.
## 4. Publish to Firefox
To publish Angular DevTools as a Firefox Add-on, first build and package the extension.
```shell
# Build the Firefox version.
yarn devtools:build:firefox
# Package the extension.
(cd dist/bin/devtools/projects/shell-browser/src/prodapp && zip -r ~/devtools-firefox.zip *)
```
Then upload it:
1. Go to the Firefox Addons [page](https://addons.mozilla.org/developers/addons)
1. Find the email and password [on Valentine](http://valentine/#/show/1651707871496288)
1. Setup Google Authenticator with the 2FA QR code.
* You can find the QR code [on Valentine as well](http://valentine/#/show/1651792043556329)
The Firefox publishing process is slightly more involved than Chrome. In particular, they
require extension source code with instructions to build and run it. Since DevTools exists in
a monorepo with critical build tooling existing outside the `devtools/` directory, we need to
upload the entire monorepo. Package it without dependencies and generated files with the
following command and upload it.
```shell
zip -r ~/angular-source.zip * -x ".git/*" -x "node_modules/*" -x "**/node_modules/*" -x "dist/"
```
Suggested note to reviewer:
> This is a monorepo and includes much more code than just the DevTools extension. The relevant
> code is under `devtools/...` and `devtools/README.md` contains instructions for compiling release
> builds locally.
>
> The uploaded source is equivalent to
> https://github.com/angular/angular/tree/${permalink to current main}/ with the single change
> of a bumped version number in the `manifest.json` file.
### 5. Commit and merge
Commit the version bump:
```shell
git checkout -b devtools-release
git add . && git commit -m "release: bump Angular DevTools version to 1.0.10"
git push -u origin devtools-release
```
Then create and merge a PR targeting `patch` with this change.
Once the PR merges and both Chrome and Firefox are showing the new version to end users, then
the release is complete!
git add . && git commit -m "release: bump Angular DevTools version to 1.0.10"
git push -u origin devtools-release
```
Then create and merge a PR targeting `patch` with this change.
Once the PR merges and both Chrome and Firefox are showing the new version to end users, then
the release is complete!