Skip to content

Commit

Permalink
Merge branch 'docs' into dev
Browse files Browse the repository at this point in the history
  • Loading branch information
@black7375
black7375 committed Apr 12, 2022
2 parents c453ef4 + efe1e83 commit cbf14cd
Show file tree
Hide file tree
Showing 14 changed files with 981 additions and 332 deletions.
271 changes: 31 additions & 240 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,11 @@
**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)
- [Modify only source file](modify-only-source-file)
- [Version](#version)
- [Branch](#branch)
- [Issue](#issue)
- [Coding style](#coding-style)
- [Commit](#commit)
- [Commit Message](#commit-message)
- [Pull request](#pull-request)
- [License](#license)
* [Code of Conduct](#code-of-conduct)
* [We Develop with Github](#we-develop-with-github)
* [Your First Contribution](#your-first-contribution)
* [Contribution Targets](#contribution-targets)
- [License](#license)
- [References](#references)

<!-- markdown-toc end -->
Expand All @@ -39,92 +25,35 @@ Please note we have a code of conduct, please follow it in all your interactions

### Code of Conduct

Refer to [CODE\_OF\_CONDUCT.md](https://github.com/black7375/Firefox-UI-Fix/blob/master/CODE_OF_CONDUCT.md).
Refer to [CODE\_OF\_CONDUCT.md](./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
[`git`](https://git-scm.com/) and [`yarn`](https://yarnpkg.com/) should be installed.

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>

## env setup
yarn install
```

You can build with this command:
```shell
yarn build
```

You can check test and css validate:
```shell
## test - When you make mixin or function
# __tests__ direcory, You can also find out how to use internal utils.
yarn test

## validate - Will be failed, this project uses non-standard features.
# Just use only for checking.
yarn validate
```

### 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)

CSS, SASS Documents:
- [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS)
- [SASS(SCSS)](https://sass-lang.com/documentation)
- [SASS Live Compile](https://www.sassmeister.com/)
**Working on your first Pull Request?**

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)
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)

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)
And, Please refer to the [development documentation](./docs/).

### 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)
**Codes**
- New Features.
- Bug fixes.
- Improved compatibility or accessibility.
- Refactoring.

**Docs**
- Fix typos, alignments.
- Correct awkward sentences.
- Improve document readability.
**Graphic Resources**
- Icons ([#213](https://github.com/black7375/Firefox-UI-Fix/issues/213), We need the help of a designer!!)
- Social preview image ([sample](https://github.com/topics/firefox-theme))

**Issues**
- Report a bug.
Expand All @@ -133,160 +62,22 @@ We love your input! We want to make contributing to this project as easy and tra
- Help other users issue.
- Proposing others..

**Codes**
- New Features.
- Bug fixes.
- Improved compatibility or accessibility.
- Refactoring.

### Project Structure

```
root
|- __tests__/: Mixin spec test
|- icons/: Icons, illustrations
|- src/: Source files
|- src/userChrome.scss: Entry of SCSS for Browser UI
|- src/userContent.scss: Entry of SCSS for Web pages
|- .gitattributes: Exclude at `Download Zip`
|- .github: Issue/PR Template, Github Actions
|- .prettierignore: Exclude coding style
|- .prettierrc.json: Coding style
|- install.ps1: Install script write in powersehll
|- install.sh: Install script write in bash
|- package.json: Build setup, package dependency
|- LEPTON: Meta infos (branch, version)
|- user.js: about:config settings
|- userChrome.css: Build result of src/userChrome.scss (Don't modify directly!!)
|- userContent.css: Build result of src/userContent.scss (Don't modify directly!!)
|- yarn.lock: Auto generated dependency (Don't modify directly!!)
```

#### 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

### Modify only source file

Do not modify files that are built directly or automatically generated.

### 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.
- `Bump:` Update dependency packages.
- `Fix:` Bug fix or change default values.
- `Clean:` Refactoring.
- `Doc:` Update docs.

### Pull request
**Docs**
- Fix typos, alignments.
- Correct awkward sentences.
- Improve document readability.

- **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.
- **Build:** Please check if it was built before PR.
**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)

### License
## License

**Any contributions you make will be under the MPL 2.0 Software License**

Expand Down
Loading

0 comments on commit cbf14cd

Please sign in to comment.