mirror of
https://github.com/XFox111/PasswordGeneratorExtension.git
synced 2026-04-22 08:08:01 +03:00
Updated Contribution Guidelines page
Eugene Fox
+233
-1
@@ -1 +1,233 @@
|
||||
TBD
|
||||
Welcome, and thank you for your interest in contributing to this project!
|
||||
|
||||
There are many ways in which you can contribute, beyond writing code. The goal of this document is to provide a high-level overview of how you can get involved.
|
||||
|
||||
## Asking Questions
|
||||
Have a question? Feel free to ask it on [GitHub Discussions board](https://github.com/XFox111/PasswordGeneratorExtension/discussions/new?category=q-a).
|
||||
|
||||
## Providing Feedback
|
||||
Your comments and feedback are welcome.
|
||||
You can leave your feedback on [GitHub Discussions](https://github.com/XFox111/PasswordGeneratorExtension/discussions) or you can leave a rated review on one of the following webstores:
|
||||
- [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/manimdhobjbkfpeeehlhhneookiokpbj)
|
||||
- [Chrome Web Store](https://chrome.google.com/webstore/detail/jnjobgjobffgmgfnkpkjfjkkfhfikmfl)
|
||||
- [Firefox Browser Add-ons](https://addons.mozilla.org/en-US/firefox/addon/easy-password-generator/)
|
||||
|
||||
## Reporting Issues
|
||||
Have you identified a reproducible problem in the extension? Have a feature request? Here's how you can make reporting your issue as effective as possible.
|
||||
|
||||
### Look For an Existing Issue
|
||||
Before you create a new issue, please do a search in [open issues](https://github.com/xfox111/PasswordGeneratorExtension/issues) to see if the issue or feature request has already been filed.
|
||||
|
||||
If you find your issue already exists, make relevant comments and add your [reaction](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments). Use a reaction in place of a "+1" comment:
|
||||
|
||||
* 👍 - upvote
|
||||
* 👎 - downvote
|
||||
|
||||
If you cannot find an existing issue that describes your bug or feature, create a new issue using the guidelines below.
|
||||
|
||||
### Writing Good Bug Reports and Feature Requests
|
||||
File a single issue per problem and feature request. Do not enumerate multiple bugs or feature requests in the same issue.
|
||||
|
||||
Do not add your issue as a comment to an existing issue unless they are the same ones. Many issues look similar, but have different causes.
|
||||
|
||||
The more information you can provide, the more likely someone will be successful at reproducing the issue and finding a solution.
|
||||
|
||||
For your convenience, we've added issue templates to make easier for you to follow these guidelines. These are available in the [new issue section](https://github.com/XFox111/PasswordGeneratorExtension/issues/new/choose).
|
||||
|
||||
### Final Checklist
|
||||
Please remember to do the following:
|
||||
- [X] Search the issue repository to ensure your report is a new issue
|
||||
- [X] Separate issues reports
|
||||
- [X] Include as much information as you can to your report
|
||||
|
||||
Don't feel bad if the developers can't reproduce the issue right away. They will simply ask for more information!
|
||||
|
||||
### Follow Your Issue
|
||||
Once your report is submitted, be sure to stay in touch with the devs in case they need more help from you.
|
||||
|
||||
## Contributing to codebase
|
||||
|
||||
> ⚠️ **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:
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
To avoid multiple pull requests resolving the same issue, make sure that you are assigned on the issue.
|
||||
|
||||
> ⚠️ **Important**
|
||||
>
|
||||
> 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
|
||||
|
||||
#### 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**
|
||||
>
|
||||
> 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
|
||||
|
||||
- [Mozilla Firefox](https://www.mozilla.org/firefox/new/)
|
||||
- [Google Chrome](https://www.google.com/chrome/)
|
||||
- [Microsoft Edge](https://www.microsoft.com/edge)
|
||||
|
||||
> ⚠️ **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.
|
||||
|
||||
|
||||
### Minor contributions
|
||||
|
||||
#### 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. **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:
|
||||
- English (`en`)
|
||||
- Polish (`pl`)
|
||||
- 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**
|
||||
>
|
||||
> 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**
|
||||
>
|
||||
> Whenever you want to contribute to the codebase, you should do it only after you got assigned on an issue
|
||||
|
||||
### Submitting pull requests
|
||||
To enable us to quickly review and accept your pull requests, always create one pull request per issue and [link the issue in the pull request](https://github.com/blog/957-introducing-issue-mentions). Never merge multiple requests in one unless they have the same root cause. Be sure to follow our [Coding Guidelines](#coding-guidelines) and keep code changes as small as possible. Avoid pure formatting changes to code that has not been modified otherwise. Fill pull request content according to its template. Deviations from the template are not recommended.
|
||||
|
||||
### Development workflow
|
||||
|
||||
This section will give you an overview of the development process. Use this steps to understand what you need to expect and do.
|
||||
|
||||
1. New issue is created
|
||||
1. Contributor is assigned to the issue
|
||||
1. A fork or a dedicated branch is created for the issue
|
||||
1. Changes to the codebase are made
|
||||
1. PR into `next` branch is opened
|
||||
1. PR passes reviews and CI checks
|
||||
1. PR is merged into `next`
|
||||
1. After some time `next` is merged into `main`
|
||||
1. New release is created
|
||||
1. The cycle repeats
|
||||
|
||||
## Thank You!
|
||||
|
||||
Your contributions to open source, large or small, make great projects like this possible. Thank you for taking the time to contribute.
|
||||
|
||||
## Attribution
|
||||
These Contribution Guidelines are adapted from the [Contributing to VS Code](https://github.com/microsoft/vscode/blob/master/CONTRIBUTING.md)
|
||||
Reference in New Issue
Block a user