swcs/simplelogin-browser-extension
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with new release process

Browse Source
This commit is contained in:
Carlos Quintana
2022-05-20 11:17:11 +02:00
parent f0de64bf95
commit 055fdf3645
2 changed files with 77 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEVELOPMENT.md
+50
View File
@@ -0,0 +1,50 @@
# DEVELOPMENT
This document contains an overview on how the extension is organized, which parts does it have and how does it work.
## General overview
The extension consists of 2 main screens:
- main screen: displays email alias recommendation, alias creation and existing alias.
- new alias screen: when a new alias is created, user is redirected to this screen so they can copy it.
## How to change the domain where the extension is connecting to
In order to change the backend URL, you will need to:
1. Copy the `.dev.sample.json` file into a `.dev.json` file.
2. Edit the `DEFAULT_API_URL` parameter and enter the URL you want to use.
3. You may need to run `npm start` again in order for the changes to take effect.
## How does the extension setup work
The extension setup process works like the following:
1. The webpage sends a message (the code can be found [here](https://github.com/simple-login/app/blob/0e3be23acc7978f6e2b1127ed78dc2147cf43515/templates/onboarding/index.html#L41-L42) and [here](https://github.com/simple-login/app/blob/0e3be23acc7978f6e2b1127ed78dc2147cf43515/templates/onboarding/setup_done.html#L31-L32))
2. The extension has a listener for events on the page, and detects it [like this](https://github.com/simple-login/browser-extension/blob/55629849838b716dabcb008898c97c4ee1118da1/src/content_script/input_tools.js#L257)
3. Once the event has been detected, the extension sends it to the background context [with this call](https://github.com/simple-login/browser-extension/blob/55629849838b716dabcb008898c97c4ee1118da1/src/content_script/input_tools.js#L260)
4. The background context [detects the event](https://github.com/simple-login/browser-extension/blob/master/src/background/index.js#L119-L120) and performs the setup. This message can only come from one of the authorized domains (see the "Add custom allowed domains" section to see how this works).
5. The setup consists on a HTTP request that will use the cookies for the SimpleLogin domain, and it will receive an API Key in the response. This API Key will be stored on the `SLStorage` and be used from then on.
6. Once the setup has been done, the user will be redirected to a page where they will be able to test the extension.
Here you have a full definition of the flow:
1. Once the extension is installed, the user will be prompted with a webpage (`/onboarding`) where two things can happen:
1. If the user is already logged in, the webpage will send the message for performing the extension setup.
1. Once the setup is done, they will be redirected to the `/onboarding/final` page.
2. If the user is not logged in, they will be prompted to log in.
1. After they log in, they will be redirected to the `/onboarding/setup_done` page.
2. The page will send the message for performing the extension setup.
3. Once the setup is done, they will be redirected to the `/onboarding/final` page.
2. Once the user reaches the `/onboarding/final` page, the extension will be correctly set up, the user will be able to use it, and the page will contain the extension version at the bottom of the page
## Add custom allowed domains
The messages for both performing the extension setup and for checking if it's installed are only allowed if they come from a [predefined set of origins](https://github.com/simple-login/browser-extension/blob/55629849838b716dabcb008898c97c4ee1118da1/src/background/index.js#L72-L77).
However, for testing purposes there is a parameter that can be added to your dev config. You can find it in your `.dev.json`, under the name `EXTRA_ALLOWED_DOMAINS`.
Keep in mind that the domains you write here will be converted to regex, so if you want to allow `*.local` you may need to write it as `.*.local`. Also take into account that only the hostname portion will be used (that means, if your page is `someserver.com:1234` only the `someserver.com` portion will be evaluated).
README.md
+24 -16
View File
@@ -21,13 +21,17 @@ More info on our website at https://simplelogin.io
The extension uses VueJS with https://github.com/Kocal/vue-web-extension boilerplate.
## General information
## How to get the extension
The extension consists of 3 main screens:
You can directly install the extension by visiting the store page for your browser:
- setup screen for first-time user. Here user can create and paste the `API Key` that's stored in `chrome.storage`.
- main screen: displays email alias recommendation, alias creation and existing alias.
- new alias screen: when a new alias is created, user is redirected to this screen so they can copy it.
- [Google Chrome / Brave / Opera / Chromium-based](https://chrome.google.com/webstore/detail/simpleloginreceive-send-e/dphilobhebphkdjbpfohgikllaljmgbn)
- [Mozilla Firefox](https://addons.mozilla.org/firefox/addon/simplelogin/)
- [Microsoft Edge](https://microsoftedge.microsoft.com/addons/detail/simpleloginreceive-sen/diacfpipniklenphgljfkmhinphjlfff)
## Development information
You can find more information about how the extension works and which parts it has in [DEVELOPMENT.md](./DEVELOPMENT.md)
## Contributing Guide
@@ -36,7 +40,6 @@ All work on SimpleLogin Chrome/Firefox extension happens directly on GitHub.
To run the extension locally, please follow these steps:
- install all dependencies with `npm install`.
- run `npm start` to generate the `/dist` folder that can be installed into Chrome.
On Firefox, it can be done via `web-ext` tool from within the `/dist` folder:
@@ -45,27 +48,32 @@ On Firefox, it can be done via `web-ext` tool from within the `/dist` folder:
( cd dist/ ; web-ext run )
```
The code is formatted using `prettier`, make sure to run it before creating the commit:
The code is formatted using `prettier`, make sure to run it before creating the commit, otherwise the GitHub lint workflow will mark the check as not passing:
```bash
npm run prettier:write
```
## How to generate a release
## Release
1. Increment the version in `package.json`.
2. Update CHANGELOG with the changes.
3. Create a tag and push it to the repository. The tag name must match the version set in `package.json`.
4. Wait until the CI process generates the extension ZIP and uploads it to GitHub. You will be able to find the generated zip as an artifact attached to the [GitHub release](https://github.com/simple-login/browser-extension/releases).
5. Upload the extension to the Chrome, Firefox and Edge stores.
- Increment the version in `package.json`
- Update CHANGELOG with the changes
- Build the production version and zip it via
```bash
npm run build && npm run build-zip
```
## How to build the extension locally
In order to build the extension yourself, please follow these steps:
- Make sure you have the dependencies installed and up-to-date with `npm install`.
- Run the build process with `npm run build`.
- Create the zip package with `npm run build-zip`. You will find the extension in the `dist-zip/` directory.
- If you want to use it on Firefox you will need to enter the `dist/` directory and run `web-ext build`. You will find the extension in the `dist/web-ext-artifacts/` directory.
- (Optional, only useful for beta build) Build beta version: change `betaRev` in `package.json`, then generate zip file using
```bash
npm run build:beta && npm run build-zip
```
- Upload to Chrome, Firefox, Edge stores.