From 082a9d66a8f939f06f38db514441a03ca04203bb Mon Sep 17 00:00:00 2001 From: Kamil Zyla Date: Fri, 30 Jun 2023 09:11:16 +0200 Subject: [PATCH 1/2] docs: Move the development section from README to CONTRIBUTING --- CONTRIBUTING.md | 44 +++++++++++++++++++++++++++++++++++++++++++ README.md | 50 ++++++------------------------------------------- 2 files changed, 50 insertions(+), 44 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..3a1dbbb1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Development + +Mbaza is based on [Electron React Boilerplate](https://github.com/electron-react-boilerplate/electron-react-boilerplate), +which uses +[Electron](https://electron.atom.io/), +[React](https://facebook.github.io/react/), +[React Router](https://github.com/reactjs/react-router), +[Webpack](https://webpack.js.org/), +[React Fast Refresh](https://www.npmjs.com/package/react-refresh). + +Useful files (sample data, biomonitoring stations, icons) +can be found on our Drive (Appsilon-internal; see bookmarks on the Slack channel) + +To be able to run inference, +download the ONNX models and place them in the `assets/models` directory: +* [Central African forests (Gabon)](https://drive.google.com/uc?export=download&id=1HHmUdq5kUib2e05YgtBQGyS-146-Q5S5) +* [East African savannas (Serengeti)](https://drive.google.com/uc?export=download&id=1UeJ4nIv_uORhmYqRGAKRjmcG39gTcBKn) +* [East African savannas (Ol Pejeta Conservancy)](https://drive.google.com/uc?export=download&id=1YpRLde9t2OL-60a0M3vNeoem5tK6JjXJ) + +The model file names should match the entries in `src/common/models.ts`. + +## Commands + +You can run the following commands from the project root. +You'll need [Node.js](https://nodejs.org/en/) 16 or later on your system. + +* `npm install`: Install dependencies. +* `npm start`: Start the app in development mode. +* `npm run lint`: Lint sources. +* `npm run lint -- --fix`: Lint sources and fix errors automatically. +* `npm run package`: Package the app for the local platform. +* `npx cross-env DEBUG_PROD=true npm run package`: Package the app with developer tools enabled. + +## Definition of Done + +1. All changes are introduced in pull requests, +which must be peer-reviewed before being merged. +2. Tasks, design decisions, etc. are described in GitHub issues and pull requests. +3. README and code comments are updated. +4. Changes are tested (manually or with automated tests): + 1. No existing functionality is broken. + 2. Installed app works well on all systems. + 3. The app can handle our sample data. +5. The code adheres to the [Airbnb style guide](https://github.com/airbnb/javascript). diff --git a/README.md b/README.md index fd73c876..c863a6a6 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ A desktop application which allows bioconservation researchers to classify camera trap animal images and analyze the results. -### Installation +## Installation Visit the [latest release page](https://github.com/Appsilon/mbaza/releases/latest) and download Mbaza installer for your system @@ -26,7 +26,7 @@ To fix it: 2. Open a terminal in the directory with the extracted app. 3. Run the following command: `xattr -cr 'Mbaza AI.app'`. -### Links +## Links * [Landing page](https://appsilon.com/data-for-good/mbaza-ai/): information, testimonials, news. @@ -35,49 +35,11 @@ information, testimonials, news. ## Development -Mbaza is based on [Electron React Boilerplate](https://github.com/electron-react-boilerplate/electron-react-boilerplate), -which uses -[Electron](https://electron.atom.io/), -[React](https://facebook.github.io/react/), -[React Router](https://github.com/reactjs/react-router), -[Webpack](https://webpack.js.org/), -[React Fast Refresh](https://www.npmjs.com/package/react-refresh). - -Useful files (sample data, biomonitoring stations, icons) -can be found on our Drive (Appsilon-internal; see bookmarks on the Slack channel) - -To be able to run inference, -download the ONNX models and place them in the `assets/models` directory: -* [Central African forests (Gabon)](https://drive.google.com/uc?export=download&id=1HHmUdq5kUib2e05YgtBQGyS-146-Q5S5) -* [East African savannas (Serengeti)](https://drive.google.com/uc?export=download&id=1UeJ4nIv_uORhmYqRGAKRjmcG39gTcBKn) -* [East African savannas (Ol Pejeta Conservancy)](https://drive.google.com/uc?export=download&id=1YpRLde9t2OL-60a0M3vNeoem5tK6JjXJ) - -The model file names should match the entries in `src/common/models.ts`. - -### Commands - -You can run the following commands from the project root. -You'll need [Node.js](https://nodejs.org/en/) 16 or later on your system. - -* `npm install`: Install dependencies. -* `npm start`: Start the app in development mode. -* `npm run lint`: Lint sources. -* `npm run lint -- --fix`: Lint sources and fix errors automatically. -* `npm run package`: Package the app for the local platform. -* `npx cross-env DEBUG_PROD=true npm run package`: Package the app with developer tools enabled. +If you are seeking to get involved in the development of Mbaza, +take a look at our [contributing guidelines](CONTRIBUTING.md). +There you'll find useful technical information about +app architecture, ML models, `npm` commands, release process, and more. ## License AGPLv3 - -## Definition of Done - -1. All changes are introduced in pull requests, -which must be peer-reviewed before being merged. -2. Tasks, design decisions, etc. are described in GitHub issues and pull requests. -3. README and code comments are updated. -4. Changes are tested (manually or with automated tests): - 1. No existing functionality is broken. - 2. Installed app works well on all systems. - 3. The app can handle our sample data. -5. The code adheres to the [Airbnb style guide](https://github.com/airbnb/javascript). From 83ad6578603f0f6f4afb72fe3a968fc76af8539e Mon Sep 17 00:00:00 2001 From: Kamil Zyla Date: Fri, 30 Jun 2023 09:31:20 +0200 Subject: [PATCH 2/2] docs: Add release intstructions to CONTRIBUTING --- CONTRIBUTING.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a1dbbb1..94c93f70 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,8 +11,10 @@ which uses Useful files (sample data, biomonitoring stations, icons) can be found on our Drive (Appsilon-internal; see bookmarks on the Slack channel) -To be able to run inference, -download the ONNX models and place them in the `assets/models` directory: +## Models + +To run inference in development mode (`npm start`) or to build the installers (`npm run package`), +you will need to download the ONNX models and place them in the `assets/models` directory: * [Central African forests (Gabon)](https://drive.google.com/uc?export=download&id=1HHmUdq5kUib2e05YgtBQGyS-146-Q5S5) * [East African savannas (Serengeti)](https://drive.google.com/uc?export=download&id=1UeJ4nIv_uORhmYqRGAKRjmcG39gTcBKn) * [East African savannas (Ol Pejeta Conservancy)](https://drive.google.com/uc?export=download&id=1YpRLde9t2OL-60a0M3vNeoem5tK6JjXJ) @@ -31,6 +33,23 @@ You'll need [Node.js](https://nodejs.org/en/) 16 or later on your system. * `npm run package`: Package the app for the local platform. * `npx cross-env DEBUG_PROD=true npm run package`: Package the app with developer tools enabled. +## Release instructions + +1. Choose a new version number according to [SemVer](https://semver.org/). +2. Update the version in the repo: + 1. Edit the `release/app/package.json` file. + 2. Update `release/app/package-lock.json` by running `npm install` in the project root. + 3. Make sure these changes are on the `main` branch before proceeding. +3. [Create a new release](https://github.com/Appsilon/mbaza/releases/new) on GitHub. +4. Build installers for the 3 operating systems: + 1. Each one needs to be built on the target system. + 2. Download the models and put them in the `assets/models` directory + (refer to the [Models](#models) section above). + 3. Run `npm install` followed by `npm run package`. + 4. The installer will be placed in the `release/build` directory. +5. Sign the Windows installer using the code signing certificate stored in our 1Password. +6. Upload the installers to the release. + ## Definition of Done 1. All changes are introduced in pull requests,