Readme & docs update

LICENSE

@@ -1,9 +1,21 @@
-Copyright (C) 2020 tarampampam <github.com/tarampampam>
+MIT License
 
-Everyone is permitted to copy and distribute verbatim or modified copies of this license
-document, and changing it is allowed as long as the name is changed.
+Copyright (c) <https://github.com/tarampampam>
 
-DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING,
-DISTRIBUTION AND MODIFICATION
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-0. You just DO WHAT THE FUCK YOU WANT TO.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -16,7 +16,7 @@ help: ## Show this help
 install: ## Install all dependencies
 	docker run $(RUN_ARGS) yarn install
 
-shell: ## Start shell into container with node
+shell: ## Start shell into a container with node
 	docker run -e "PS1=\[\033[1;34m\]\w\[\033[0;35m\] \[\033[1;36m\]# \[\033[0m\]" -i $(RUN_ARGS) sh
 
 build: ## Build the extension (for the production)

README.md

@@ -1,42 +1,46 @@
+<p align="center"><img width="84" alt="logo" src="https://hsto.org/webt/zh/yz/3t/zhyz3t3knfyukt8pfnshd_xehrm.png"></p>
+<p align="center">Automatically <strong>replaces the User-Agent</strong> with a <strong>randomized one</strong>.</p>
+<br/>
 <p align="center">
-  <img alt="logo" src="https://hsto.org/webt/ll/p7/zn/llp7zncabngc8lnfynz9-wm0zni.png" height="80" />
+  <a href="https://chrome.google.com/webstore/detail/random-hide-user-agent/einpaelgookohagofgnnkcfjbkkgepnp/"><img alt="Chrome Web Store" src="https://img.shields.io/chrome-web-store/v/einpaelgookohagofgnnkcfjbkkgepnp.svg?style=for-the-badge&cacheSeconds=120&logo=google-chrome&label=google%20chrome&logoColor=white"></a> &nbsp; <a href="https://addons.mozilla.org/firefox/addon/random_user_agent/"><img alt="Firefox Add-ons" src="https://img.shields.io/amo/v/random_user_agent.svg?style=for-the-badge&cacheSeconds=120&logo=firefox-browser&label=firefox&logoColor=white"></a> &nbsp; <a href="#"><img alt="Edge Addons" src="https://img.shields.io/badge/Edge-555555.svg?&style=for-the-badge&logo=microsoft-edge&logoColor=white"></a>
 </p>
-
-# Random User-Agent
-
-[![Release version][badge_release_version]][link_changelog]
-[![Chrome WebStore version][badge_websore_version]][link_google_store]
-[![License][badge_license]][link_license]
-
-Automatically replaces the User-Agent after a specified time interval
+<h1 align="center">Random User-Agent</h1>
+<br/>
+<p align="center">Random User-Agent is an <strong>open-source</strong> MIT-licensed <strong>browser extension</strong> that is designed to replaces original browser User-Agent identifier (is a sort of "fingerprint") with a randomized. The extension is incredibly lightweight, using very few resources.</p>
+<br/>
+<br/>
 
 ![Screenshot](https://hsto.org/webt/cl/cz/iv/clczivrmvn47ryadjvtyb13qqom.jpeg)
 
-User-Agent - a string that is sent along to any website you visit. This is a sort of "fingerprint" your browser leaves behind which contains:
+## 🔥 Features list
 
-- The name and version of your browser;
-- The name of the operating system (Mac, Windows, Linux, etc.) and its version;
-- Information about some plugins installed on the browser;
-- Other information that identifies and exposes you.
+- Incredibly lightweight (`~70KiB` archived)
+- Available in the official stores ([chrome][link-chrome-store], [firefox][link-ff-store], [edge][link-edge-store])
+- Can automatically change the User-Agent after a specified period of time
+- Change User-Agent on browser startup
+- Replaces `User-Agent` HTTP header
+- Protect against detection by JavaScript
+- User-Agent randomization can be customized by the user (what browsers and OS are spoofed, etc.)
+- Exceptions list available with option of wildcards
 
-This extension has been created to stop data leakage. It automatically replaces User-Agent strings after a specified period of time with a randomly selected one. User-Agent strings can also be set manually. The extension is incredibly lightweight, using very few resources. User-Agent randomization can be customized by the user (what browsers and OS are spoofed, etc.). Exceptions list available with option of wildcards. Protects against Javascript exploits to hide your identity and protect your anonymity.
+## 👀 Questions
 
-> **Warning**
->
-> Depending on your threat model, faking your user agent might make you _more_ fingerprintable, not less. There are ways other than `User-Agent` sniffing to determine what browser you're using, so malicious sites could learn what browser you're _really_ using through other means and then combine that with your randomly changing `User-Agent` to pretty effectively track you. For background, see [this GitHub issue](https://github.com/tarampampam/random-user-agent/issues/47). You've been warned.
-
-## How to translate (localize) this extension?
-
-The translation process described [here](./public/_locales).
+Most questions can be answered by reading the [issues][issues]. If the issues doesn't answer your question, open up a
+new [discussion][discussions].
 
-## Where can I check the functionality?
+<details>
+  <summary>This extension may actually be making users more uniquely fingerprintable, not less?</summary>
 
-- <https://tarampampam.github.io/random-user-agent/>
-- <https://webbrowsertools.com/useragent/>
+Faking your user agent might make you _more_ fingerprintable, not less. There are ways other than `User-Agent` sniffing
+to determine what browser you're using, so malicious sites could learn what browser you're _really_ using through other
+means and then combine that with your randomly changing `User-Agent` to pretty effectively track you. For background,
+see [this GitHub issue](https://github.com/tarampampam/random-user-agent/issues/47).
+</details>
 
-## Known issues
+<details>
+  <summary>User-agent can't be replaced (for now) in Google Chrome for pages with aggressive (inline JavaScript) detection</summary>
 
-User-agent can't be replaced (for now) in Google Chrome for pages with aggressive (inline JavaScript) detection. For example:
+Example:
 
 ```html
 <!doctype html>
@@ -49,27 +53,69 @@ User-agent can't be replaced (for now) in Google Chrome for pages with aggressiv
 </html>
 ```
 
-This method is quite rare (usually JavaScript code is wrapped in `Promises`, `setTimeout` or event listeners), but so far no way around this kind of checking has been invented.
+This method is quite rare (usually JavaScript code is wrapped in `Promises`, `setTimeout` or event listeners), but so
+far no way around this kind of checking has been invented.
+</details>
+
+## 🧩 Install
+
+Follow up by one of the links at the top 👆 of this page, or download directly the latest from
+the [releases page][releases].
+
+## 🖥️ Run Locally
+
+After cloning the project, open the terminal and navigate to the project root directory (since I am a Linux adept, for
+the following commands installed `docker` and `make` are required):
+
+```bash
+$ make install # install all node dependencies
+
+$ make watch # watch for source changes
+
+$ make shell # start shell into a container with node
+
+$ make build # build the extension
+```
+
+After `make watch` command you can:
+
+1. Open chrome and navigate to extensions page using this URL: `chrome://extensions`
+2. Make sure "**Developer mode**" is enabled
+3. Click "**Load unpacked extension**" button, browse the `./dist` directory and select it
+4. Write something awesome (don't forget to make a PR after that)
+
+## 📜 How to translate (localize) this extension?
+
+The translation process described [here](./public/_locales).
+
+## 🦾 Contributors
 
-### Useful links for developers
+I want to say a big thank you to everyone who contributed to this project:
 
-- [Manifest file format (v3)](https://developer.chrome.com/docs/extensions/mv3/manifest/)
-- [Chrome Extension TypeScript Starter](https://github.com/chibat/chrome-extension-typescript-starter)
+![contrib](https://contrib.rocks/image?repo=tarampampam/random-user-agent)
 
-## TODO
+> And a special thanks to [@neroux](https://github.com/neroux) - dude, you're awesome
 
-- [ ] Translation platform integration
-- [ ] Provide donation link
-- [ ] Dark theme `@media (prefers-color-scheme: dark) {`
-- [ ] Sentry or something similar
-- [ ] Use the <https://github.com/mozilla/webextension-polyfill>
+## 🚀 Release
 
-[badge_release_version]:https://img.shields.io/github/release/tarampampam/random-user-agent.svg?style=for-the-badge&maxAge=120&logo=github&logoColor=white
-[badge_websore_version]:https://img.shields.io/chrome-web-store/v/einpaelgookohagofgnnkcfjbkkgepnp.svg?style=for-the-badge&maxAge=120&logo=google-chrome&logoColor=white
-[badge_license]:https://img.shields.io/github/license/tarampampam/random-user-agent.svg?style=for-the-badge&maxAge=120
+> This note is for me, so as not to forget anything...
 
-[link_changelog]:./CHANGELOG.md
-[link_license]:./LICENSE
-[link_google_store]:https://chrome.google.com/webstore/detail/random-hide-user-agent/einpaelgookohagofgnnkcfjbkkgepnp
+1. Make required changes in this repository, test it locally
+2. Update [changelog file](CHANGELOG.md) and "publish" new release using repo [releases page][releases]
+3. When the CI process is done - download the file `random-user-agent.zip` to my computer
+4. Open "[Chrome Web Store Developer Dashboard][chrome-upload-new]" and click the "Upload new package" button, next, next... Publish
+5. Download the `main.crx` file from the dashboard, rename it to the `random-user-agent.crx` and upload to the [release on GitHub][releases]
+6. Open "[Mozilla add-on developer hub][ff-upload-new]", "Select a file...", next, next, download the extension sources archive, upload it to hub, next, Publish
+7. Download the `random_user_agent_X.X.X-blabla.xpi` file from the dashboard, rename it to the `random-user-agent.xpi` and upload to the [release on GitHub][releases]
+8. Don't forget to update the fkn edge store
+9. Open a beer, I've earned
 
+[chrome-upload-new]:**https://chrome.google.com/webstore/devconsole/ea9e18ff-c849-424a-acba-9b43eaad29c8/einpaelgookohagofgnnkcfjbkkgepnp/edit/package
+[ff-upload-new]:https://addons.mozilla.org/en-US/developers/addon/random_user_agent/versions/submit/
 
+[issues]:https://github.com/tarampampam/random-user-agent/issues
+[discussions]:https://github.com/tarampampam/random-user-agent/discussions
+[releases]:https://github.com/tarampampam/random-user-agent/releases
+[link-chrome-store]:https://chrome.google.com/webstore/detail/random-hide-user-agent/einpaelgookohagofgnnkcfjbkkgepnp
+[link-ff-store]:https://addons.mozilla.org/firefox/addon/random_user_agent/
+[link-edge-store]:#

TODO.md

@@ -0,0 +1,7 @@
+# TODO
+
+- [ ] Translation platform integration
+- [ ] Provide donation link
+- [ ] Dark theme `@media (prefers-color-scheme: dark) {`
+- [ ] Sentry or something similar
+- [ ] Use the <https://github.com/mozilla/webextension-polyfill>