269 lines
10 KiB
Markdown
269 lines
10 KiB
Markdown
# Contributing
|
||
|
||
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
|
||
**Table of Contents**
|
||
|
||
- [Introduce](#introduce)
|
||
- [Code of Conduct](#code-of-conduct)
|
||
- [We Develop with Github](#we-develop-with-github)
|
||
- [Environment](#environment)
|
||
- [Your First Contribution](#your-first-contribution)
|
||
- [Contribution Targets](#contribution-targets)
|
||
- [Project Structure](#project-structure)
|
||
- [Icon files](#icon-files)
|
||
- [Meta Info files](#meta-info-files)
|
||
- [Restrictions](#restrictions)
|
||
- [Rules](#rules)
|
||
- [Version](#version)
|
||
- [Branch](#branch)
|
||
- [Issue](#issue)
|
||
- [Coding style](#coding-style)
|
||
- [Commit](#commit)
|
||
- [Commit Message](#commit-message)
|
||
- [Pull request](#pull-request)
|
||
- [License](#license)
|
||
- [References](#references)
|
||
|
||
<!-- markdown-toc end -->
|
||
|
||
## Introduce
|
||
|
||
I'm really glad you're reading this, because we need volunteer developers to help this project come to fruition.
|
||
|
||
Please note we have a code of conduct, please follow it in all your interactions with the project.
|
||
|
||
### Code of Conduct
|
||
|
||
Refer to [CODE\_OF\_CONDUCT.md](https://github.com/black7375/Firefox-UI-Fix/blob/master/CODE_OF_CONDUCT.md).
|
||
|
||
### We Develop with Github
|
||
|
||
We use [github](https://github.com/black7375/Firefox-UI-Fix) to host code, to track [issues](https://github.com/black7375/Firefox-UI-Fix/issues) and feature requests, as well as accept [pull requests](https://github.com/black7375/Firefox-UI-Fix/pulls).
|
||
|
||
After feedback has been given we expect responses within two weeks. After two weeks we may close the issue and pull request if it isn't showing any activity.
|
||
|
||
### Environment
|
||
|
||
You can configure it as follows:
|
||
```shell
|
||
## clone repository
|
||
git clone https://github.com/black7375/Firefox-UI-Fix.git
|
||
cd ./Firefox-UI-Fix
|
||
|
||
## checkout branch
|
||
git checkout <BRANCH_NAME>
|
||
```
|
||
|
||
### Your First Contribution
|
||
|
||
**Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
|
||
|
||
The following documents may be helpful:
|
||
- [Roadmap](https://github.com/black7375/Firefox-UI-Fix/issues/2)
|
||
- [Each Versions Plan](https://github.com/black7375/Firefox-UI-Fix/milestones)
|
||
- [Wiki:Compatibility Issues Solution](https://github.com/black7375/Firefox-UI-Fix/wiki/Compatibility-Issues-Solution)
|
||
- [Wiki:Tips](https://github.com/black7375/Firefox-UI-Fix/wiki/Tips)
|
||
|
||
Live Debugging:
|
||
- [Tutorial: How to create and live-debug userChrome.css](https://www.reddit.com/r/FirefoxCSS/comments/73dvty/tutorial_how_to_create_and_livedebug_userchromecss/)
|
||
- [Browser Toolbox](https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox)
|
||
- [Style Editor](https://developer.mozilla.org/en-US/docs/Tools/Style_Editor)
|
||
|
||
Firefox Source Code:
|
||
- [Github](https://github.com/mozilla/gecko-dev)
|
||
- [Searchfox](https://searchfox.org/)
|
||
- [Firefox Source Docs](https://firefox-source-docs.mozilla.org/)
|
||
|
||
Test for None mac users:
|
||
- [Docker-OSX](https://github.com/sickcodes/Docker-OSX)
|
||
|
||
### Contribution Targets
|
||
|
||
We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
|
||
|
||
**Promotions**
|
||
- Introduce project
|
||
- Video (Recommend!!, We need it)
|
||
- Blog
|
||
- SNS
|
||
- Reddit, Hackernews..etc
|
||
- Sample
|
||
- [Producthunt](https://www.producthunt.com/posts/firefox-ui-fix-proton)([#43](https://github.com/black7375/Firefox-UI-Fix/issues/43))
|
||
- [Youtube](https://www.youtube.com/watch?v=ECta0icNMgY)
|
||
|
||
**Docs**
|
||
- Fix typos, alignments.
|
||
- Correct awkward sentences.
|
||
- Improve document readability.
|
||
|
||
**Issues**
|
||
- Report a bug.
|
||
- Discussing the current state of the code.
|
||
- Tell us about related or relevant projects and documents.
|
||
- Help other users issue.
|
||
- Proposing others..
|
||
|
||
**Codes**
|
||
- New Features.
|
||
- Bug fixes.
|
||
- Improved compatibility or accessibility.
|
||
- Refactoring.
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
root
|
||
|- .gitattributes: Exclude at `Download Zip`
|
||
|- .github: Issue/PR Template, Github Actions
|
||
|- .prettierignore: Exclude coding style
|
||
|- .prettierrc.json: Coding style
|
||
|- icons/: Icons, illustrations
|
||
|- install.ps1: Install script write in powersehll
|
||
|- install.sh: Install script write in bash
|
||
|- LEPTON: Meta infos (branch, version)
|
||
|- user.js: about:config settings
|
||
|- userChrome.css: CSS for Browser UI
|
||
|- userContent.css: CSS for Web pages
|
||
```
|
||
|
||
#### Icon files
|
||
|
||
Most of them are made in SVG.
|
||
|
||
Except for illustrations, there must be an `fill="context-fill" fill-opacity="context-fill-opacity"` property to dynamically determine color and transparency.
|
||
|
||
Icons are mainly [FirefoxUX/photon-icons](https://github.com/FirefoxUX/photon-icons)
|
||
or [microsoft/fluentui-system-icons](https://github.com/microsoft/fluentui-system-icons).
|
||
|
||
#### Meta Info files
|
||
|
||
It comes from [install.sh](https://github.com/black7375/Firefox-UI-Fix/blob/01ae88bf2c4710e1f364d9eb2901ca2b722cefe7/install.sh#L442).
|
||
|
||
**`LEPTON` file format**
|
||
|
||
If this file exist in same directory as the `userChrome.css` file,
|
||
it is recognized as the "Lepton" installation directory.
|
||
|
||
```ini
|
||
[Info]
|
||
Branch=master | photon-style | proton-style
|
||
Ver=<git tag> | <git hash> | [NULL]
|
||
```
|
||
|
||
**`lepton.ini` file Format**
|
||
|
||
In `lepton.ini`, various information is stored during the installation process.\
|
||
This file is recreated every time the installer is created.
|
||
|
||
```ini
|
||
[Profile Name]
|
||
Type=Local | Release | Git
|
||
Branch=master | photon-style | proton-style
|
||
Ver=<git tag> | <git hash> | [NULL]
|
||
Path=<Full PATH>
|
||
```
|
||
|
||
**Update Policy according to `Type`**
|
||
- Local(unknown): force latest commit update
|
||
- Release(<git tag>): force latest tag update
|
||
- Git<git hash>: latest commit update
|
||
|
||
### Restrictions
|
||
|
||
- Cross Platform
|
||
- Different compatibility issues occur in Win7, Win8, Win10, KDE, Gnome, Mac, etc.
|
||
- Consider compatibility as much as possible, but use [dedicated media queries](https://github.com/mozilla/gecko-dev/blob/d6188c9ce02efeea309e7177fc14c9eb2f09db37/servo/components/style/gecko/media_features.rs#L906-L930) in special cases
|
||
- CSS Loading Order
|
||
- User CSS(`userChrome.css`, `userContent.css`) is usually loaded first.
|
||
- In many cases, overriding should be prevented with [`important!`](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity#the_!important_exception)(Anti-pattern in general web), and side effects should also be considered.
|
||
- DOM structure cannot be modified
|
||
- It is possible with JS, but there are security and configuration issues, so we should make the most of CSS.
|
||
- [`::before`](https://developer.mozilla.org/en-US/docs/Web/CSS/::before) and [`::after`](https://developer.mozilla.org/en-US/docs/Web/CSS/::after) can indirectly add CSS elements.
|
||
- [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)
|
||
- Firefox actively uses shadow dom internally
|
||
- To modify, it is often a roundabout approach or impossible to inherit
|
||
- [XUL](https://en.wikipedia.org/wiki/XUL)
|
||
- Sometimes written and bound in C++ for performance, like a treeview of bookmarks.
|
||
- The proper document does not exist, so we have to read the source code and work
|
||
- Available CSS features are also restricted.
|
||
- Side Effects
|
||
- Only CSS modifications can cause bugs that are hard to think of in the general web, such as the [context menu not appearing](https://github.com/black7375/Firefox-UI-Fix/issues/114).
|
||
|
||
## Rules
|
||
|
||
### Version
|
||
|
||
Milestone, The versioning scheme we use is [SemVer](https://semver.org/). (Maintainer decides, do not pull request.)
|
||
|
||
We will release the feature as soon as it is complete, but the cycle should be 2-4 weeks.
|
||
Rapid releases.
|
||
|
||
It comes from [#109](https://github.com/black7375/Firefox-UI-Fix/issues/109#issuecomment-873313945).
|
||
|
||
### Branch
|
||
|
||
Stable: Only bugfix, Documentation.
|
||
- `master`: Common bugfix, documentation.
|
||
- `photon-style`: Bugfix, documentation specified in `photon-style`.
|
||
- `proton-sryle`: Bugfix, documentation specified in `proton-style`.
|
||
|
||
Development: New Features.
|
||
- `dev`: Common new features.
|
||
- `photon-style-dev`: New features specified in `photon-style`.
|
||
- `proton-style-dev`: New features specified in `proton-style`.
|
||
|
||
### Issue
|
||
|
||
- **Versions:**
|
||
- Make sure you’re on the latest version.
|
||
- Try older versions.
|
||
- Try switching up dependency versions.
|
||
- **Search:** Search the project’s [issues](https://github.com/black7375/Firefox-UI-Fix/issues) to make sure it's not a known issue.
|
||
|
||
### Coding style
|
||
|
||
- **Indent:** 2 spaces for indentation rather than tabs.
|
||
- **Columns:** Fit `80`~`100` columns as much as possible. (Auto formatting is using 120 to avoid the worst case)
|
||
|
||
### Commit
|
||
|
||
- **Meaningfully:**: It doesn't make meaningless commits.
|
||
- **One per task:** It's difficult to distinguish when various tasks are mixed.
|
||
- **Often:** Codes may corrupt during large changes.
|
||
|
||
### Commit Message
|
||
|
||
For intuitive recognition, I [put a **prefix**](https://github.com/black7375/Firefox-UI-Fix/commits/master).
|
||
- `Add:` Add feature or enhanced.
|
||
- `Fix:` Bug fix or change default values.
|
||
- `Clean:` Refactoring.
|
||
- `Doc:` Update docs.
|
||
|
||
### Pull request
|
||
|
||
- **Branch:** Check the [Branch](#branch) section and PR to the correct branch.
|
||
- **Issue:** We recommend that you open the issue first to discuss the changes with the owner of this repository.
|
||
|
||
### License
|
||
|
||
**Any contributions you make will be under the MPL 2.0 Software License**
|
||
|
||
In short, when you submit code changes, your submissions are understood to be under the same [MPL 2.0 License](https://choosealicense.com/licenses/mpl-2.0/) that covers the project.
|
||
Feel free to contact the maintainers if that's a concern.
|
||
|
||
**Reference specification**
|
||
|
||
Even if you copy the code snippet, it is recommended that you leave a link.
|
||
|
||
**FAQ**
|
||
|
||
If you have any questions about other licenses, please see [Moailla's MPL 2.0 FAQ](https://www.mozilla.org/en-US/MPL/2.0/FAQ/).
|
||
|
||
|
||
## References
|
||
|
||
- [Good-CONTRIBUTING.md-template](https://gist.github.com/PurpleBooth/b24679402957c63ec426)
|
||
- [Contributing to Transcriptase](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62)
|
||
- [contributing-template](https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md)
|
||
- [Contributing to Open Source Projects](https://www.contribution-guide.org/)
|