parent
7b41f3b7b2
commit
4b6bb52952
81
CONTRIBUTING.md
Normal file
81
CONTRIBUTING.md
Normal file
@ -0,0 +1,81 @@
|
|||||||
|
# Issues and Features
|
||||||
|
|
||||||
|
Issues reported on [GitHub](https://github.com/FooSoft/yomichan/issues) should include information about:
|
||||||
|
|
||||||
|
* What the problem, question, or request is.
|
||||||
|
* What browser is being used.
|
||||||
|
* What version of Yomichan is being used.
|
||||||
|
* If applicable, an export of the settings file.
|
||||||
|
|
||||||
|
# Development
|
||||||
|
|
||||||
|
Contributions are welcome from any developers who would like to help out.
|
||||||
|
Below are a few guidelines to ensure contributions have a good level of quality and consistency:
|
||||||
|
|
||||||
|
* Open GitHub issues to discuss large features before writing code.
|
||||||
|
* Follow the [conventions and style](#style) of the existing code.
|
||||||
|
* Test changes using the continuous integration tests included in the repository.
|
||||||
|
* Write clean, modern ES6 code (`const`/`let`, `async`/`await`, arrow functions, etc.)
|
||||||
|
* Large pull requests without a clear scope will not be merged.
|
||||||
|
* Incomplete or non-standalone features will not be merged.
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
Yomichan uses [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) tools for building and testing.
|
||||||
|
After installing these Node.js, the development environment can be set up by running `npm ci`.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Unit tests, integration tests, and various other tests can be executed by running `npm test`.
|
||||||
|
Other individual tests can be looked up in the [package.json](package.json) file, and the source for specific tests
|
||||||
|
can be found in the [test](test) directory
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
By default, the development repository is configured for Chrome, and the [ext](ext) directory can be directly
|
||||||
|
loaded as an unpacked extension by Chrome. This way, development does not require any additional build steps,
|
||||||
|
and most changes will be automatically updated by the browser. Depending on what files were changed,
|
||||||
|
the extension may sometimes need to be reloaded before the changes take effect.
|
||||||
|
|
||||||
|
|
||||||
|
There are two scripts to build the extension to a packaged file for various build targets:
|
||||||
|
* [build.bat](build.bat) on Windows
|
||||||
|
* [build.sh](build.sh) on Linux
|
||||||
|
|
||||||
|
Both of these files are convenience scripts which invoke <code>node [dev/build.js](dev/build.js)</code>.
|
||||||
|
The build script can produce several different build files based on manifest configurations defined in
|
||||||
|
[manifest-variants.json](dev/data/manifest-variants.json).
|
||||||
|
Several command line arguments are available for these scripts:
|
||||||
|
|
||||||
|
* `[target]` - Builds a specific target.
|
||||||
|
* `--all` - Builds all targets specified in [manifest-variants.json](dev/data/manifest-variants.json).
|
||||||
|
* `--default` - Restores the default manifest file.
|
||||||
|
* `--manifest <target>` - Overwrites [ext/manifest.json](ext/manifest.json) with the manifest variant for the specified build target.
|
||||||
|
* `--dry-run` - Runs the full build process (excluding zip building), checking that the configuration is valid.
|
||||||
|
* `--dry-run-build-zip` - If `--dry-run` is also specified, zip building will also be performed in memory; no files are created.
|
||||||
|
|
||||||
|
If no arguments are specified, the command is equivalent to `build.bat --all`.
|
||||||
|
|
||||||
|
### Build Tools
|
||||||
|
|
||||||
|
The build process can use the [7-zip](https://www.7-zip.org/) archiving tool to create the packed zip builds
|
||||||
|
if the 7-zip executable (either `7z` or `7za`) is found in the `PATH` environment variable.
|
||||||
|
Otherwise, the [JSZip](https://stuk.github.io/jszip/) API is used to generate the files.
|
||||||
|
7-zip typically provides better compression than JSZip, but the files are otherwise equivalent.
|
||||||
|
|
||||||
|
## Manifest
|
||||||
|
|
||||||
|
Manifest variants for different build targets are specified in [manifest-variants.json](dev/data/manifest-variants.json).
|
||||||
|
This file is used to overwrite the [manfiest.json](ext/manifest.json) file included in the extension.
|
||||||
|
By default, this manifest should be the default `chrome` manifest, and changes to [manfiest.json](ext/manifest.json) should not be committed
|
||||||
|
unless there is a corresponding change in [manifest-variants.json](dev/data/manifest-variants.json).
|
||||||
|
There is a continuous integration test which validates this, and the default manifest can be restored by running
|
||||||
|
`build.bat --default`.
|
||||||
|
|
||||||
|
## Style
|
||||||
|
|
||||||
|
Linting rules are defined for a few types of files, and validation is performed as part of the standard tests
|
||||||
|
run by `npm test` and the continuous integration process.
|
||||||
|
|
||||||
|
* [.eslintrc.json](.eslintrc.json) rules are used for JavaScript files.
|
||||||
|
* [.stylelintrc.json](.stylelintrc.json) rules are used for CSS files.
|
45
README.md
45
README.md
@ -14,7 +14,7 @@ Yomichan provides advanced features not available in other browser-based diction
|
|||||||
* Custom search page for easily executing custom search queries.
|
* Custom search page for easily executing custom search queries.
|
||||||
* Support for multiple dictionary formats including [EPWING](https://ja.wikipedia.org/wiki/EPWING) via the [Yomichan Import](https://foosoft.net/projects/yomichan-import) tool.
|
* Support for multiple dictionary formats including [EPWING](https://ja.wikipedia.org/wiki/EPWING) via the [Yomichan Import](https://foosoft.net/projects/yomichan-import) tool.
|
||||||
* Automatic note creation for the [Anki](https://apps.ankiweb.net/) flashcard program via the [AnkiConnect](https://foosoft.net/projects/anki-connect) plugin.
|
* Automatic note creation for the [Anki](https://apps.ankiweb.net/) flashcard program via the [AnkiConnect](https://foosoft.net/projects/anki-connect) plugin.
|
||||||
* Clean, modern code makes it easy for developers to [contribute](https://github.com/FooSoft/yomichan) new features.
|
* Clean, modern code makes it easy for developers to [contribute](https://github.com/FooSoft/yomichan/blob/master/CONTRIBUTING.md) new features.
|
||||||
|
|
||||||
## Table of Contents ##
|
## Table of Contents ##
|
||||||
|
|
||||||
@ -26,11 +26,9 @@ Yomichan provides advanced features not available in other browser-based diction
|
|||||||
* [Flashcard Configuration](#flashcard-configuration)
|
* [Flashcard Configuration](#flashcard-configuration)
|
||||||
* [Flashcard Creation](#flashcard-creation)
|
* [Flashcard Creation](#flashcard-creation)
|
||||||
* [Keyboard Shortcuts](#keyboard-shortcuts)
|
* [Keyboard Shortcuts](#keyboard-shortcuts)
|
||||||
* [Development](#development)
|
|
||||||
* [Dependencies](#dependencies)
|
|
||||||
* [Frequently Asked Questions](#frequently-asked-questions)
|
* [Frequently Asked Questions](#frequently-asked-questions)
|
||||||
|
* [Licenses](#licenses)
|
||||||
* [Screenshots](#screenshots)
|
* [Screenshots](#screenshots)
|
||||||
* [License](#license)
|
|
||||||
|
|
||||||
## Installation ##
|
## Installation ##
|
||||||
|
|
||||||
@ -244,31 +242,6 @@ Shortcut | Action
|
|||||||
<kbd>Alt</kbd> + <kbd>p</kbd> | Play audio for current term.
|
<kbd>Alt</kbd> + <kbd>p</kbd> | Play audio for current term.
|
||||||
<kbd>Alt</kbd> + <kbd>k</kbd> | Add current kanji to Anki.
|
<kbd>Alt</kbd> + <kbd>k</kbd> | Add current kanji to Anki.
|
||||||
|
|
||||||
## Development ##
|
|
||||||
|
|
||||||
As feature development and improvements to Yomichan can be time consuming, contributions are welcome from
|
|
||||||
any developers who want to help out. Below are a few guidelines to ensure contributions have a good level
|
|
||||||
of quality and consistency:
|
|
||||||
|
|
||||||
* Open GitHub issues to discuss large features before writing code.
|
|
||||||
* Follow the [conventions and style](.eslintrc.json) of the existing code.
|
|
||||||
* Test changes using the continuous integration tests included in the repository (`npm ci; npm test`).
|
|
||||||
* Write clean, modern ES6 code (`const`/`let`, `async`/`await`, arrow functions, etc.)
|
|
||||||
* Large pull requests without a clear scope will not be merged.
|
|
||||||
* Incomplete or non-standalone features will not be merged.
|
|
||||||
|
|
||||||
### Dependencies ###
|
|
||||||
|
|
||||||
Yomichan uses several third-party libraries to function. Below are links to homepages, snapshots, and licenses of the exact
|
|
||||||
versions packaged.
|
|
||||||
|
|
||||||
* Bootstrap: [homepage](https://getbootstrap.com/) - [snapshot](https://github.com/twbs/bootstrap/releases/download/v3.3.7/bootstrap-3.3.7-dist.zip) - [license](https://github.com/twbs/bootstrap/blob/v3.3.7/LICENSE)
|
|
||||||
* Handlebars: [homepage](https://handlebarsjs.com/) - [snapshot](http://builds.handlebarsjs.com.s3.amazonaws.com/handlebars.min-714a4c4.js) - [license](https://github.com/wycats/handlebars.js/blob/v4.0.6/LICENSE)
|
|
||||||
* jQuery: [homepage](https://blog.jquery.com/) - [snapshot](https://code.jquery.com/jquery-3.2.1.min.js) - [license](https://github.com/jquery/jquery/blob/3.2.1/LICENSE.txt)
|
|
||||||
* JSZip: [homepage](https://stuk.github.io/jszip/) - [snapshot](https://raw.githubusercontent.com/Stuk/jszip/de7f52fbcba485737bef7923a83f0fad92d9f5bc/dist/jszip.min.js) - [license](https://github.com/Stuk/jszip/blob/v3.1.3/LICENSE.markdown)
|
|
||||||
* WanaKana: [homepage](https://wanakana.com/) - [snapshot](https://unpkg.com/wanakana@4.0.2/umd/wanakana.min.js) - [license](https://github.com/WaniKani/WanaKana/blob/4.0.2/LICENSE)
|
|
||||||
* parse5: [homepage](https://github.com/inikulin/parse5) - [snapshot](https://github.com/inikulin/parse5/tree/v6.0.1/packages/parse5) - [license](https://github.com/inikulin/parse5/blob/v6.0.1/LICENSE) _(Only used in MV3 build)_
|
|
||||||
|
|
||||||
## Frequently Asked Questions ##
|
## Frequently Asked Questions ##
|
||||||
|
|
||||||
**I'm having problems importing dictionaries in Firefox, what do I do?**
|
**I'm having problems importing dictionaries in Firefox, what do I do?**
|
||||||
@ -339,7 +312,7 @@ languages would not only require many additional changes to the codebase, it wou
|
|||||||
overhead and knowledge demands for the developers. Therefore, suggestions and contributions for supporting
|
overhead and knowledge demands for the developers. Therefore, suggestions and contributions for supporting
|
||||||
new languages will be declined, allowing Yomichan's focus to remain Japanese-centric.
|
new languages will be declined, allowing Yomichan's focus to remain Japanese-centric.
|
||||||
|
|
||||||
## Legal ##
|
## Licenses ##
|
||||||
|
|
||||||
Required licensing notices for this project follow below:
|
Required licensing notices for this project follow below:
|
||||||
|
|
||||||
@ -355,6 +328,18 @@ Required licensing notices for this project follow below:
|
|||||||
The pitch accent notation, verb particle data, phonetics, homonyms and other additions or modifications to EDICT,
|
The pitch accent notation, verb particle data, phonetics, homonyms and other additions or modifications to EDICT,
|
||||||
KANJIDIC or KRADFILE were provided by Uros Ozvatic through his free database.
|
KANJIDIC or KRADFILE were provided by Uros Ozvatic through his free database.
|
||||||
|
|
||||||
|
### Third-Party Libraries ###
|
||||||
|
|
||||||
|
Yomichan uses several third-party libraries to function. Below are links to homepages, snapshots, and licenses of the exact
|
||||||
|
versions packaged.
|
||||||
|
|
||||||
|
* Bootstrap: [homepage](https://getbootstrap.com/) - [snapshot](https://github.com/twbs/bootstrap/releases/download/v3.3.7/bootstrap-3.3.7-dist.zip) - [license](https://github.com/twbs/bootstrap/blob/v3.3.7/LICENSE)
|
||||||
|
* Handlebars: [homepage](https://handlebarsjs.com/) - [snapshot](http://builds.handlebarsjs.com.s3.amazonaws.com/handlebars.min-714a4c4.js) - [license](https://github.com/wycats/handlebars.js/blob/v4.0.6/LICENSE)
|
||||||
|
* jQuery: [homepage](https://blog.jquery.com/) - [snapshot](https://code.jquery.com/jquery-3.2.1.min.js) - [license](https://github.com/jquery/jquery/blob/3.2.1/LICENSE.txt)
|
||||||
|
* JSZip: [homepage](https://stuk.github.io/jszip/) - [snapshot](https://raw.githubusercontent.com/Stuk/jszip/de7f52fbcba485737bef7923a83f0fad92d9f5bc/dist/jszip.min.js) - [license](https://github.com/Stuk/jszip/blob/v3.1.3/LICENSE.markdown)
|
||||||
|
* WanaKana: [homepage](https://wanakana.com/) - [snapshot](https://unpkg.com/wanakana@4.0.2/umd/wanakana.min.js) - [license](https://github.com/WaniKani/WanaKana/blob/4.0.2/LICENSE)
|
||||||
|
* parse5: [homepage](https://github.com/inikulin/parse5) - [snapshot](https://github.com/inikulin/parse5/tree/v6.0.1/packages/parse5) - [license](https://github.com/inikulin/parse5/blob/v6.0.1/LICENSE) _(Only used in MV3 build)_
|
||||||
|
|
||||||
## Screenshots ##
|
## Screenshots ##
|
||||||
|
|
||||||
[![Term definitions](https://foosoft.net/projects/yomichan/img/ss-terms-thumb.png)](https://foosoft.net/projects/yomichan/img/ss-terms.png)
|
[![Term definitions](https://foosoft.net/projects/yomichan/img/ss-terms-thumb.png)](https://foosoft.net/projects/yomichan/img/ss-terms.png)
|
||||||
|
Loading…
Reference in New Issue
Block a user