From 18fe5a230040a7a3df8efc24ddc56f62286ab682 Mon Sep 17 00:00:00 2001 From: Gaurav Agarwal Date: Sun, 16 Jan 2022 00:23:57 +0530 Subject: [PATCH] Added CONTRIBUTING.md #799 (#800) * Signed off by @gaurav7019 --- CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++++++++++++++ README.md | 8 +++++--- 2 files changed, 48 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..72604be7f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,43 @@ +# Kiwix JS Contribution Guide + +If you have some development experience with HTML and JavaScript, we welcome Pull Requests on existing issues. Please look at this repository's Issue +tracker, in particular those marked "good first issue". If you have found a bug, check first that we do not have an existing issue covering it, and if not, feel free to create an issue. + +Please follow these guidelines when contributing: + +- Ask to be assigned to an issue you wish to work on first (we have lots of past issues, some of which are no longer relevant or wanted); +- We ask you only to pick issues for which you are confident that you have a solution; +- If you are a newcomer to the repo, create a personal fork and clone it locally (for more details, see [Kiwix guidelines](https://github.com/kiwix/overview/blob/master/CONTRIBUTING.md)). Check out a new branch with a name relevant to the issue you are working on; +- Follow the coding style of the area you are editing, including indentation, and be consistent with quotation marks and spacing; +- Use no higher than [ECMAScript 5](https://caniuse.com/es5) - notably, do not use arrow functions or `async` functions. However, Promises *are* + supported via a polyfill; +- Do not prettify code you are not working on; +- You must test your code yourself before asking for review, like this: + - set up a local Web server (we recommend Node/NPM's [http-server](https://www.npmjs.com/package/http-server)); + - serve the root directory of the repository (e.g. `http-server .`); + - in a browser, navigate to the URL of the main `index.html` (e.g. http://localhost:8080/www/index.html); + - manually test your fix in at least Firefox and Chromium (Edge or Chrome), ideally also in IE11 or in "IE Mode" in Edge; + - be sure to test your fix in both "JQuery" mode and "Service Worker" mode (see Configuration); + - run the Unit tests (see below) in at least the above browsers. + +If all the tests are working fine, you can finally test the extension versions, like this: + + - Remove the '-WIP' from the version key from the manifest.json file present in the root of this repo; + - In Chromium, you can install the extension by loading the root folder with Extensions -> Load Unpacked (with Developer Mode turned ON) -> select the root folder of the repository; + - In Firefox, you can load an extension with Manage Your Extensions -> Debug Add-ons -> Load Temporary Add-on, and then pick any file in the repository. + +If your feature works and tests are passing, make a PR, describe the testing you have done, and ask for a code review. + +Please note that the app caches its own code so that it can run as an offline-first Progressive Web App. This can complicate development, because you +may not see your changes, even after you refresh the browser. In Configuration, under "Expert settings", you will find a button that allows you to do +a full app reset, which will erase the PWA. When Service Worker mode is turned on, there is also a checkbox that bypasses the App Cache. You can turn +this on if you are frequently changing code and refreshing. Remember to turn it off for final testing. You can manually delete the App Cache in +the browser's DevTools (see Application or Storage tabs). We also recommend you disable the browser's built-in cache, using the checkbox in the DevTools Network tab. + +## Unit tests + +Basic UI tests can be run by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server. + +You can also run the UI tests with npm. Before running the tests, a one-time setup is needed to fetch development dependencies from the npm registry. +Run `npm ci --ignore-scripts` to fetch the same versions as we use in CI. Then run `npm test` to run the tests against Chrome and Firefox headless +(these browsers need to be installed in default locations). diff --git a/README.md b/README.md index 4020a43b5..100d45ac6 100644 --- a/README.md +++ b/README.md @@ -83,11 +83,13 @@ Although the app has fast title search, it cannot yet do full text search of the This application is released under the GPL v3 licence. See http://www.gnu.org/licenses/ or the included LICENSE-GPLv3.txt file The source code can be found at https://github.com/kiwix/kiwix-js. -## Unit tests +## Contributing -Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome. +Kiwix JS is an open-source project. We encourage individuals with experience of HTML and JavaScript development to contribute to the documentation and code in this repository. -Before running the tests, a one-time set up is needed to fetch development dependencies from the npm registry. Run `npm ci --ignore-scripts` to fetch the same versions as we use in CI. +For code contributions, read our [CONTRIBUTING](CONTRIBUTING.md) guide. + +To get to know the Kiwix project better, please familiarize yourself with the content on https://www.kiwix.org. There is also a Kiwix [Slack](https://join.slack.com/t/kiwixoffline/shared_invite/enQtOTUyMTg4NzMxMTM4LTU0MzYyZDliYjdmMDYzYWMzNDA0MDc4MWE5OGM0ODFhYjAxNWIxMjVjZTU4MTkyODJlZWFkMmQ2YTZkYTUzZDY) group which you can join. ## Public releases and nightly builds