diff --git a/.github/workflows/publish-extension.yaml b/.github/workflows/publish-extension.yaml index 363705cf..9e6d3ba6 100644 --- a/.github/workflows/publish-extension.yaml +++ b/.github/workflows/publish-extension.yaml @@ -90,6 +90,8 @@ jobs: git config user.email "<>" # Delete gitignore entry for the dist folder sed -i "/^\/dist\/$/d" .gitignore + # Apply the patch to gitignore to allow some dependencies to be included + git apply ./scripts/gitignore.patch if [ ! -z "$(git status --porcelain)" ]; then git add . git commit -m "Set GitHub Pages release version" diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c127f1d5..68d8a63d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,14 +27,16 @@ do a one-time setup before you start coding, like this: and for Windows [here](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows); * Create a personal fork of Kiwix JS and clone it locally (for more details, see [Kiwix guidelines](https://github.com/kiwix/overview/blob/main/CONTRIBUTING.md)); * In a Terminal (Bash, PowerShell) run `npm install` in the project's root directory to install development and bundling dependencies; -* Test the development server by running `npm run serve`. This will open the (unbundled) source code in your browser. **While viewing this, we strongly recommend - that you go to configuration and turn on the option to Bypass AppCache under "Expert Settings", as this will ensure you are always looking at the latest version - (otherwise the app caches its own code, and you won't see your changes easily)**. You can exit this server by typing `q` in the Terminal that launched it; +* Test the development server by running `npm run serve`. This will open the (unbundled) source code in your browser. **While viewing this, we strongly recommend** + **that you go to configuration and turn on the option to Bypass AppCache under "Expert Settings", as this will ensure you are always looking at the latest version** + (otherwise the app caches its own code, and you won't see your changes easily). You can exit this server by typing `q` in the Terminal that launched it; * Test that bundling works by running `npm run preview`. This should build the app and launch a preview of the production code in a server. Again, we strongly recommend, - while here, that you turn on the Bypass AppCache option. To exit this server, press `Ctrl-C` in the Terminal that launched it. + while here, that you **turn on the Bypass AppCache option**. To exit this server, press `Ctrl-C` in the Terminal that launched it; +* You can build the bundled version without previewing it with `npm run build`. It will be built to the `/dist` directory. -You can use any Integrated Development Environment (IDE) that you wish. If you don't have a preference, we can recommend [Visual Studio Code](https://code.visualstudio.com/). -If using this, also install the [ESLint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) within VS Code. +You can use any Integrated Development Environment (IDE) that you wish. If you don't have a preference, we can recommend +[Visual Studio Code](https://code.visualstudio.com/). If using this, also install the +[ESLint plugin](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) within VS Code. ## Contributing guidelines diff --git a/README.md b/README.md index bd82fd65..8ec27b07 100644 --- a/README.md +++ b/README.md @@ -82,8 +82,11 @@ would suggest that you upgrade to a browser that supports Service Workers (Chrom These platforms/browsers are deprecated. We still partially test against them, and we'll try to keep compatibility as long as it's not too complicated: - Firefox OS >=1.2 (needs to be installed manually on the device with WebIDE) -- Microsoft Edge Legacy >=15 (needs to run a local copy of the source code) -- Microsoft Internet Explorer 11 (needs to run a local copy of the source code) +- Microsoft Edge Legacy >=15 (needs to run a bundled version of the source code) +- Microsoft Internet Explorer 11 (needs to run a bundled version of the source code) + +You can build a bundled version by running `npm install` and `npm run build` in the root directory of this repo. Alternatively, a bundled version is served +as a web app for testing from https://kiwix.github.io/kiwix-js/dist/ (also available on the `gh-pages` branch of this repo, under `/dist`). ### Installing unsigned extensions in Chromium @@ -135,7 +138,9 @@ The browser extensions are distributed through the stores of each vendor (see li Some nightly builds are generated, and should only be used for testing purpose: https://download.kiwix.org/nightly/. -There is a test implementation of the latest code at https://kiwix.github.io/kiwix-js/, but this is used for development, and may be buggy, experimental or unstable. +There is a test implementation of the latest code at https://kiwix.github.io/kiwix-js/ (unbundled: needs a modern browser that suppors native ES6 modules), and a bundled version for any +HTML5 browser (>=IE11) at https://kiwix.github.io/kiwix-js/dist/, but these implementations are used for development, and may be buggy, experimental or unstable. A stable PWA version for +use in the browser extensions is available from https://browser-extension.kiwix.org/current/. ## Previous versions diff --git a/scripts/gitignore.patch b/scripts/gitignore.patch new file mode 100644 index 00000000..e9824797 --- /dev/null +++ b/scripts/gitignore.patch @@ -0,0 +1,42 @@ +# DEV: This patch file is used in the publish-extension.yaml workflow to allow some dependenicies in node_modules to be committed to the repo +# in the gh-pages branch. This is needed because the gh-pages branch is used to publish an implementation of the app. You may need to maintain +# this list if more dependencies are added to the extension via npm. + .gitignore | 24 +++++++++++++++++++++++- + 1 file changed, 23 insertions(+), 1 deletion(-) + +diff --git a/.gitignore b/.gitignore +index 69d180f..45218ed 100644 +--- a/.gitignore ++++ b/.gitignore +@@ -43,7 +43,29 @@ build/config/buildinfo.properties + + www-built + www-ghdeploy +-/node_modules/ ++/node_modules/* ++!/node_modules/@fortawesome ++/node_modules/@fortawesome/* ++!/node_modules/@fortawesome/fontawesome-free ++/node_modules/@fortawesome/fontawesome-free/* ++!/node_modules/@fortawesome/fontawesome-free/js ++/node_modules/@fortawesome/fontawesome-free/js/* ++!/node_modules/@fortawesome/fontawesome-free/js/all.js ++!/node_modules/bootstrap ++/node_modules/bootstrap/* ++!/node_modules/bootstrap/dist ++/node_modules/bootstrap/dist/* ++!/node_modules/bootstrap/dist/css ++/node_modules/bootstrap/dist/css/* ++!/node_modules/bootstrap/dist/css/bootstrap.min.* ++!/node_modules/bootstrap/dist/js ++/node_modules/bootstrap/dist/js/* ++!/node_modules/bootstrap/dist/js/bootstrap.bundle.min.* ++!/node_modules/jquery ++/node_modules/jquery/* ++!/node_modules/jquery/dist ++/node_modules/jquery/dist/* ++!/node_modules/jquery/dist/jquery.slim.min.* + /tmp/ + /scripts/kiwix-*.pem + /scripts/set_secret_environment_variables.sh + \ No newline at end of file