Updated Contribution Guidelines (markdown)

Contribution-Guidelines.md

@@ -47,40 +47,36 @@ Once your report is submitted, be sure to stay in touch with the devs in case th
 
 ## Contributing to codebase
 
-> ⚠️ **Important**
+> [!IMPORTANT]
->
 > Whenever you want to contribute to the codebase, you should do it only after you got assigned on an issue
 
 If you are interested in writing code to fix issues or implement new awesome features you can follow this guidelines to get a better result.
 
 ### Finding an issue to work on
-Check out the [issues section](https://github.com/XFox111/PasswordGeneratorExtension/issues) for a list of all potential areas for contributions. **Note** that just because an issue exists in the repository does not mean we will accept a contribution. There are several reasons we may not accept a pull request like:
+Check out the [issues section](https://github.com/XFox111/PasswordGeneratorExtension/issues) for a list of all potential areas for contributions.
 
-- Performance - One of project's core values is to deliver a lightweight extension, that means it should perform well in both real and test environments.
+To improve the chances to get a pull request merged you should select an issue that is [labeled with the `help-wanted` label](https://github.com/XFox111/PasswordGeneratorExtension/issues?q=label%3A%22help+wanted%22). If the issue you want to work on is not labeled with `help-wanted`, you can start a conversation with the project maintainers asking whether an external contribution will be considered.
-- User experience - Since we want to deliver a lightweight extension, the UX should feel lightweight as well and not be cluttered. Most changes to the UI should go through the issue owner and the project owner (@xfox111).
-- Architectural - Project owner needs to agree with any architectural impact a change may make. Such things must be discussed with and agreed upon by the project owner.
 
-To improve the chances to get a pull request merged you should select an issue that is [labeled with the `help-wanted` label](https://github.com/XFox111/PasswordGeneratorExtension/issues?q=label%3A%22help+wanted%22). If the issue you want to work on is not labeled with `help-wanted`, you can start a conversation with the project owner asking whether an external contribution will be considered.
+> [!IMPORTANT]
+Just because an issue exists in the repository does not mean we will accept a contribution.
 
 To avoid multiple pull requests resolving the same issue, make sure that you are assigned on the issue.
 
-> ⚠️ **Important**
+> [!WARNING]
->
 > Avoid working on an issue that is not assigned to you (especially, when it is assigned to someone else!) We may reject these PRs!
 
 ### Setting up development environment
 
-> ℹ️ **Note:** If you use Dev Containers or GitHub Codespaces, you can skip this section
+> [!NOTE]
+> If you use Dev Containers or GitHub Codespaces, you can skip this section
 
 #### Prerequisites
 
 - [Node.js 20](https://nodejs.org/)
-- [Yarn](https://yarnpkg.com/) (usually comes pre-installed with Node.js)
 - [VS Code](https://code.visualstudio.com/) (optional, but strongly recommended)
 
-> ℹ️ **Note**
+> [!TIP]
->
+> It is strongly recommended to use VS Code editor during development, since this repository comes with pre-defined rules, extensions and other features for the VS Code that will significantly simplify development process.
-> It is strongly recommended to use VS Code editor during development, since this repository comes with pre-defined rules, extensions and other features for the VSC that will significantly simplify development process.
 
 #### Target browsers
 
@@ -88,91 +84,35 @@ To avoid multiple pull requests resolving the same issue, make sure that you are
 - [Google Chrome](https://www.google.com/chrome/)
 - [Microsoft Edge](https://www.microsoft.com/edge)
 
-> ⚠️ **Important**
+### Development
->
+
+Once you have cloned the repository you can execute following commands:
+
+> [!TIP]
+> If you use VS Code, you can use pre-defined tasks to run most of required actions (`F1` -> `Tasks: Run Task`)
+
+| Name | Default | Chrome | Firefox | Edge |
+| --- | --- | --- | --- | --- |
+| 1. Install dependencies | `npm install` | N/A | N/A | N/A |
+| 2. Dev (debug in browser with live updates) | `npm run dev` (Chrome) | `npm run dev:chrome` | `npm run dev:firefox` | `npm run dev:edge` |
+| 3. Build | `npm run build` (Chrome) | `npm run build:chrome` | `npm run build:firefox` | `npm run build:edge` |
+| 4. Create archive | `npm run zip` (Chrome) | `npm run zip:chrome` | `npm run build:firefox` | - |
+
+> [!CAUTION]
+`npm run dev:firefox` uses MV2 which is incompatible with some of used APIs (e.g. `browser.action`). When testing on Firefox it is recommended to use `npm run build:firefox` and then sideloading the extension.
+
+> [!IMPORTANT]
+Before debugging, you may need to set your browser binaries location, or otherwise configure debugging environment. Please refer to [web-ext.config.ts](https://wxt.dev/guide/directory-structure/web-ext-config.html) of the WXT framework for more details.
+
+#### Sideloading
+
+Before submitting your PR, make sure you have tested the final extension via sideloading.
+
+You can find sideloading instructions in the project's [README](https://github.com/XFox111/PasswordGeneratorExtension/blob/main/README.md#sideloading-for-testing-purposes-only).
+
+> [!IMPORTANT]
 > Before submitting your PR, make sure you've tested the extension on both Firefox and at least one Chromium-based browser, since these browser have only partially compatible APIs. It is recommended to test the extension only on target browsers.
 
-To get started with development, go through these steps:
-
-1. Clone the repository
-1. Open a new terminal in the repository root and run `yarn install` command to restore dependencies
-1. Run `yarn build` command to build the extension for Chromium browsers
-
-#### Targeting Firefox
-
-When targeting Firefox you need to specify `TARGET` environment variable before executing `yarn build` and `yarn dev` commands. This is how you can do:
-
-```shell
-# Bash
-$ TARGET=firefox yarn build|dev
-# PowerShell
-PS> $env:TARGET="firefox"; yarn build|dev
-# Windows CMD
-> set TARGET=firefox  && yarn build|dev
-```
-
-> ℹ️ **Note**
->
-> If you use VS Code, you can use pre-defined tasks to run these actions (`F1` -> `Tasks: Run Task`). There are three tasks defined: `Restore dependencies`, `Build: Chromium/Firefox`, `Watch: Chromium/Firefox`, `Dev: Chromium/Firefox`
-
-### Debugging the extension
-
-There are several ways to run and debug the extension. You can use any of them based on what is most suitable for you.
-
-#### Option 1. Development mode
-
-> - ✅ The most simple
-> - ✅ Supports hot reloading
-> - ✅ Automated sideloading
-> - ✅ Fast
-> - ❌ Highly unstable (may crash or just don't work)
-> - ❌ May require some customizations ([docs](https://vite-plugin-web-extension.aklinker1.io/guide/supporting-multiple-browsers.html))
-
-This option is the most simple and flexible. It supports hot reloading, so every time you change the code it will instantly reflect changes in a browser. Be aware that it is the most unstable as well.
-
-To run the extension in Development mode use following command:
-```bash
-$ yarn dev
-```
-
-Learn more about Development and Watch modes [here](https://vite-plugin-web-extension.aklinker1.io/guide/development.html).
-
-#### Option 2. Watch mode
-
-> - ✅ Simple enough
-> - ✅ Supports hot reloading
-> - ✅ Automated sideloading
-> - ⚠️ Mildly unstable (hot reload may not work)
-> - ❌ Slow
-> - ❌ May require some customizations ([docs](https://vite-plugin-web-extension.aklinker1.io/guide/supporting-multiple-browsers.html))
-
-This option is a convenient alternative if for some reason you can't use Development mode. Be aware that this approach takes significantly longer to reflect changes as it makes a full rebuild of the extension each time you change the source code.
-
-To run the extension in Watch mode use following command:
-```bash
-$ yarn build --watch --mode development
-```
-
-Learn more about Development and Watch modes [here](https://vite-plugin-web-extension.aklinker1.io/guide/development.html).
-
-#### Option 3. Sideloading
-
-> - ✅ The most stable
-> - ✅ Doesn't require any customizations
-> - ⚠️ Mildly complicated
-> - ❌ Slow
-> - ❌ No hot reload
-> - ❌ Manual sideloading/reloading
-
-This option is the most time consuming but it will work regardless of your environment.
-
-1. Build the extension for your target browser (`chrome` or `firefox`)
-1. Sideload your build into your browser ([follow this instruction](https://github.com/XFox111/PasswordGeneratorExtension/blob/main/README.md#sideloading-for-testing-purposes-only))
-1. Test the extension
-1. Repeat the cycle
-
-This option is optimal if you make small changes, so you don't need to recompile the extension more than 1-2 times.
-
 ### Coding guidelines
 
 Please refer to the [Code style guidelines](https://github.com/XFox111/PasswordGeneratorExtension/wiki/Code-style) to learn more about code formatting rules for this project.
@@ -183,28 +123,21 @@ Please refer to the [Code style guidelines](https://github.com/XFox111/PasswordG
 #### Contributing to translations
 If you want to help us to translate this extension into other languages, please follow these steps:
 
-1. **Go to `src/Data/Locales` folder.**
+1. **Go to `locales` folder.**
-1. **Choose locale file that you will use as a base for your translation** (e.g., if you were to add Belorussian translation it would be better to use Ukrainian, Polish or Russian locales as a base). There are several locales exist to consider:
+1. **Choose a locale file that you will use as a base for your translation.**
-	- English (`en`)
+1. **Duplicate selected file and rename it with appropriate [language code](https://developer.chrome.com/docs/extensions/reference/i18n/#supported-locales)** (e.g. if you were to add a French locale, the file and its path path would be: `locales/fr.yml`).
-	- Polish (`pl`)
+1. **Open the file in text editor and familiarize yourself with it's structure.**
-	- Ukrainian (`uk`)
-	- Brazilian Portuguese (`pt_BR`)
-	- Russian (`ru`)
-1. **Copy selected file to a new directory with appropriate [language code](https://developer.chrome.com/docs/extensions/reference/i18n/#supported-locales)** (e.g., if you were to add a French locale the file's path would be: `src/Data/Locales/fr/messages.json`).
-1. **Open the file in text editor and familiarize yourself with it's structure.** [Read this article](https://developer.chrome.com/docs/extensions/reference/i18n/#searching-for-messages) if you have any troubles.
 1. **Translate text in file.** Make sure that you translate only necessary text (use other locale files as a reference on what you should translate). Do not translate anything else.
 1. **Build and test the extension** to review your locale. This step is optional, but it will help you to catch all discrepancies and typos.
 1. **Commit the changes and open a PR.**
 
-> ℹ️ **Advice**
+> [!TIP]
->
+> Try adapting text instead of just translating word-to-word. Some sentences don't make sense in one language, but do in others.
-> Try adapting the text instead of just translating word-to-word. Some sentences don't make sense in one language, but do in others.
 
 #### Spell check errors
 Pull requests that fix typos are welcomed but please make sure it doesn't touch multiple feature areas, otherwise it will be difficult to review. Pull requests only fixing spell check errors in source code (not visible in UI) are not recommended.
 
-> ⚠️ **Important**
+> [!IMPORTANT]
->
 > Whenever you want to contribute to the codebase, you should do it only after you got assigned on an issue
 
 ### Submitting pull requests