Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
dgp1130 wants to merge 1 commit into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 0 additions & 39 deletions devtools/DEVELOPING.md
View file
Open in desktop

This file was deleted.

114 changes: 40 additions & 74 deletions devtools/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
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).
Second, install [Yarn](https://classic.yarnpkg.com/en/):

### 3. Publish to Chrome Chrome
```shell
npm install -g yarn@1
```

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

```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 *)
yarn --frozen-lockfile
```

Then upload it to the Chrome Web Store.
Now you should be ready to build the DevTools extension.

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"
### Dev builds

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.
To run the extension in development mode run:

### 4. Firefox
```shell
yarn devtools:devserver
```

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

```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 *)
yarn devtools:devserver:demo-standalone
```

Then upload it:
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.

1. Go to the Firefox Addons [page](https://addons.mozilla.org/developers/addons)
1. For email enter `[email protected]`
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
### Release builds

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.
You can build the release version of Angular DevTools for either Chrome or Firefox with:

```shell
zip -r ~/angular-source.zip * -x ".git/*" -x "node_modules/*" -x "**/node_modules/*" -x "dist/"
yarn devtools:build:chrome
yarn devtools:build:firefox
```

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

> 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.
#### Installation

### 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
```
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).

Then create and merge a PR targeting `patch` with this change.
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.

Once the PR merges and both Chrome and Firefox are showing the new version to end users, then
the release is complete!
113 changes: 113 additions & 0 deletions devtools/docs/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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!