From e7138c26e504d296b058ee1033838dc85f17a562 Mon Sep 17 00:00:00 2001 From: gaurav7019 Date: Fri, 14 Jan 2022 02:13:39 +0530 Subject: [PATCH 1/7] Added CONTRIBUTING.md : WIP --- CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++ README.md | 8 ++++++++ 2 files changed, 39 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..ec7d8d5cb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# 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". Please follow these guidelines when contributing: + +- Ask to be assigned to an issue you wish to work on first (we have lots of back 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. Chekout a new branch with a name relavant 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: + - clone the repository; + - 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 test the actual extension version in the end, like this: + - Remove the '-WIP' from the version key from the manifest.json file present in the root of this repo; + - Load the root folder manually in chrome(or any other browser) to install the extension; + +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). diff --git a/README.md b/README.md index 98bee1170..2dd3c1a71 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,14 @@ These platforms are deprecated. We still partially test against them, and we'll This application is released under the GPL v3 license. 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 +## Contributing + +The Kiwix JS project is being developed as open source. It is being actively maintainted on Github and we encourage individuals to contribute to the documentation and code. + +Join the Kiwix [Slack](https://join.slack.com/t/kiwixoffline/shared_invite/enQtOTUyMTg4NzMxMTM4LTU0MzYyZDliYjdmMDYzYWMzNDA0MDc4MWE5OGM0ODFhYjAxNWIxMjVjZTU4MTkyODJlZWFkMmQ2YTZkYTUzZDY) working group to get involved! + +For code contributions, read our [CONTRIBUTING](CONTRIBUTING.md) guide. + ## Unit tests Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome. From 5309f55e7c525c07426bd4ff2328cb8a9f49eb3a Mon Sep 17 00:00:00 2001 From: gaurav7019 Date: Fri, 14 Jan 2022 12:46:38 +0530 Subject: [PATCH 2/7] Added CONTRIBUTING.md --- CONTRIBUTING.md | 16 ++++++++++------ README.md | 6 +++--- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ec7d8d5cb..7eb53274f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,30 @@ # 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". Please follow these guidelines when contributing: +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 back 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. Chekout a new branch with a name relavant to the issue you are working on; +- If you are a newcomer to the repo, create a personal fork and clone it locally. 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: - - clone the repository; - 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 test the actual extension version in the end, like this: + +If all the tests are working fine, you can test the actual extension version in the end, like this: + - Remove the '-WIP' from the version key from the manifest.json file present in the root of this repo; - - Load the root folder manually in chrome(or any other browser) to install the extension; + - In Chromium, you can install the extension by loading the root folder with Extensions -> Load Unpacked(with Developer Mode turned ON) -> selecting 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. @@ -28,4 +32,4 @@ Please note that the app caches its own code so that it can run as an offline-fi 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). +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. diff --git a/README.md b/README.md index 2dd3c1a71..01282e139 100644 --- a/README.md +++ b/README.md @@ -59,12 +59,12 @@ The source code can be found at https://github.com/kiwix/kiwix-js ## Contributing -The Kiwix JS project is being developed as open source. It is being actively maintainted on Github and we encourage individuals to contribute to the documentation and code. - -Join the Kiwix [Slack](https://join.slack.com/t/kiwixoffline/shared_invite/enQtOTUyMTg4NzMxMTM4LTU0MzYyZDliYjdmMDYzYWMzNDA0MDc4MWE5OGM0ODFhYjAxNWIxMjVjZTU4MTkyODJlZWFkMmQ2YTZkYTUzZDY) working group to get involved! +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. 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. + ## Unit tests Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome. From cc7ae17bcfccde5a06918788393650fd10f24d59 Mon Sep 17 00:00:00 2001 From: gaurav7019 Date: Fri, 14 Jan 2022 13:21:30 +0530 Subject: [PATCH 3/7] Added CONTRIBUTING.md : addressed review --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7eb53274f..d49efd614 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,10 +20,10 @@ Please follow these guidelines when contributing: - 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 test the actual extension version in the end, like this: +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) -> selecting the root folder of the repository; + - 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. From d6caa889681dcf479130cacf401eb7ed76eda967 Mon Sep 17 00:00:00 2001 From: gaurav7019 Date: Sat, 15 Jan 2022 00:11:21 +0530 Subject: [PATCH 4/7] Updated contributing.md from review --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d49efd614..238585b41 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ tracker, in particular those marked "good first issue". If you have found a bug, Please follow these guidelines when contributing: -- Ask to be assigned to an issue you wish to work on first (we have lots of back issues, some of which are no longer relevant or wanted); +- 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. 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; From 7a9b41cd3a7279ea6f84cf6da63de9035da84ec6 Mon Sep 17 00:00:00 2001 From: gaurav7019 Date: Sat, 15 Jan 2022 23:09:03 +0530 Subject: [PATCH 5/7] Moved unit tests to contributing.md --- CONTRIBUTING.md | 6 ++++++ README.md | 6 ------ 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 238585b41..48287dc6a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,3 +33,9 @@ may not see your changes, even after you refresh the browser. In Configuration, 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 + +Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome. + +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. diff --git a/README.md b/README.md index 01282e139..0bfb71604 100644 --- a/README.md +++ b/README.md @@ -65,12 +65,6 @@ 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. -## Unit tests - -Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome. - -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. - ## Public releases and nightly builds The browser extensions are distributed through the stores of each vendor (see links above). But the packages are also saved in https://download.kiwix.org/release/browsers/ if necessary. From 067a5a8822bf41048bc8808fb6b9962e6892448a Mon Sep 17 00:00:00 2001 From: gaurav7019 Date: Sat, 15 Jan 2022 23:33:37 +0530 Subject: [PATCH 6/7] Added contributing guidelines' link --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 48287dc6a..d80686444 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ 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. Check out a new branch with a name relevant to the issue you are working on; +- 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; From c831c1d6c470880a8dbcfca57fa1d59e4847a231 Mon Sep 17 00:00:00 2001 From: gaurav7019 Date: Sat, 15 Jan 2022 23:38:41 +0530 Subject: [PATCH 7/7] Updated unit test section --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d80686444..72604be7f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,8 @@ the browser's DevTools (see Application or Storage tabs). We also recommend you ## Unit tests -Unit tests can be run by opening `tests/index.html` file in Firefox, Edge, or Chromium/Chrome. +Basic UI tests can be run by opening `tests/index.html` in Firefox, Edge, or Chromium/Chrome through a (local) web server. -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. +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).