alex/yomichan
1
Fork 0
Code Releases Activity

Add contributing file (#1305)

Browse Source 
* Add CONTRIBUTING.md

* Update README.md
This commit is contained in:
toasted-nutbread 2021-01-24 10:49:06 -05:00 committed by GitHub
parent 7b41f3b7b2
commit 4b6bb52952
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 96 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
CONTRIBUTING.md Normal file
View 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
View File

@ -14,7 +14,7 @@ Yomichan provides advanced features not available in other browser-based diction
* 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.
* 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 ##
@ -26,11 +26,9 @@ Yomichan provides advanced features not available in other browser-based diction
* [Flashcard Configuration](#flashcard-configuration)
* [Flashcard Creation](#flashcard-creation)
* [Keyboard Shortcuts](#keyboard-shortcuts)
* [Development](#development)
* [Dependencies](#dependencies)
* [Frequently Asked Questions](#frequently-asked-questions)
* [Licenses](#licenses)
* [Screenshots](#screenshots)
* [License](#license)
## Installation ##
@ -244,31 +242,6 @@ Shortcut | Action
<kbd>Alt</kbd> + <kbd>p</kbd> | Play audio for current term.
<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 ##
**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
new languages will be declined, allowing Yomichan's focus to remain Japanese-centric.
## Legal ##
## Licenses ##
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,
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 ##
[![Term definitions](https://foosoft.net/projects/yomichan/img/ss-terms-thumb.png)](https://foosoft.net/projects/yomichan/img/ss-terms.png)