From 564cffcaa15fe28a02b97659020b5674795898d5 Mon Sep 17 00:00:00 2001 From: Alexandre Neuwald CTW Date: Wed, 8 May 2024 12:05:20 +0100 Subject: [PATCH] update readme --- CONTRIBUTING.md | 86 +++++++++------ Dockerfile | 8 +- README.md | 103 ++++++++++++++---- .../CurrentLayoutProvider/defaultLayout.ts | 4 +- packages/studio-web/src/webpackConfigs.ts | 2 +- resources/screenshot.png | 4 +- 6 files changed, 146 insertions(+), 61 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e064ae814b..acc6078c58 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,75 @@ -# Contributing to Foxbox +# Contributing Guidelines -**Supported development environments:** Linux, Windows, macOS +Welcome, and thank you for your interest in contributing to FoxBox! We value your contributions and want to make the contributing experience enjoyable and rewarding for you. Here’s how you can get started: -**Dependencies:** +## :rocket: Getting Started -- [Node.js](https://nodejs.org/en/) v16.10+ -- [Git LFS](https://git-lfs.github.com/) +Please check our [README.md](../README.md) and follow the installation steps. -## Getting started - -1. Clone repo -1. Run `git lfs pull` to ensure Git LFS objects are up to date -1. Run `corepack enable` and `yarn install` - - If you still get errors about corepack after running `corepack enable`, try uninstalling and reinstalling Node.js. Ensure that Yarn is not separately installed from another source, but is installed _via_ corepack. -1. Launch the development environment: +#### Other useful commands ```sh -# To launch the desktop app (run both scripts concurrently): -$ yarn desktop:serve # start webpack -$ yarn desktop:start # launch electron - -# To launch the browser app: -$ yarn web:serve - -# To launch the storybook: +# To launch the storybook $ yarn storybook +``` +```sh # Advanced usage: running webpack and electron on different computers (or VMs) on the same network -$ yarn desktop:serve --host 192.168.xxx.yyy # the address where electron can reach the webpack dev server +$ yarn desktop:serve --host 192.168.xxx.yyy # the address where electron can reach the webpack dev server $ yarn dlx electron@22.1.0 .webpack # launch the version of electron for the current computer's platform ``` -### Other useful commands - ```sh -$ yarn run # list available commands -$ yarn lint # lint all files -$ yarn test # run all tests -$ yarn test:watch # run tests on changed files +$ yarn run # list available commands +$ yarn lint # lint all files +$ yarn test # run all tests +$ yarn test:watch # run tests on changed files +$ yarn test:integration # run all integration tests ``` -## Localization +## :herb: Creating a new branch + +To create a branch in this repository, please follow the guidelines below, ensuring that the purpose of each branch is clear and well-defined: + +- `feature` : Create this branch when adding new features, modifying existing features, or removing outdated functionality. +- `bugfix` : This branch is for resolving bugs discovered in existing features. +- `hotfix` : Use this for rapidly addressing critical issues. This typically involves implementing a temporary solution that requires immediate attention. +- `test` : This is intended for experimental changes, where the main goal is to explore new ideas or test solutions without addressing a specific issue. +- `docs` : Designate this branch for updates and improvements to documentation, ensuring that information is current and helpful to users. +- `wip` (Work In Progress): Use this for ongoing development that is not yet ready for merging into the main branch. + +### Examples + +`feature/new-menu-foo` + +`test/create-unit-test-for-component-bar` + +## :label: Version increment + +Semantic Versioning has been chosen as our standard method for version increments, which is widely adopted across various software projects. The version format is structured as follows: +`..[.]`. + +- _Note: Currently, the version increment process is manual. Developers are required to update the version number in the package.json file manually. An automated pipeline for this task is in development and will be implemented to streamline this process in the future._ + +### Components + +MAJOR: Increasing the major version usually breaks compatibility, allowing developers to remove the deprecated API or rework the existing ones. Users know about it and do not expect a smooth update. + +MINOR: Version increment implies adding new functionality without breaking compatibility. + +PATCH: Also known as bugfix version that includes fixing security vulnerabilities, etc. + +BUILD NUMBER (Optional): Optionally, the build number can be additionally added. + +### Examples + +`1.20.11` + +`1.20.11.403` -At this time, first-class support for Foxbox is provided in English only. Localization into other languages is available on a best-effort basis, with translations provided by community volunteers. Current community supported-languages are: +## :globe_with_meridians: Localization -- Chinese -- Japanese +At this time, first-class support for Foxbox is provided in English only. Localization into other languages is available on a best-effort basis, with translations provided by community volunteers. Translation support is implemented using [`react-i18next`](https://react.i18next.com). diff --git a/Dockerfile b/Dockerfile index 00212f5b66..456af2ded3 100644 --- a/Dockerfile +++ b/Dockerfile @@ -17,11 +17,11 @@ EXPOSE 8080 COPY < index.html # Continue executing the CMD diff --git a/README.md b/README.md index a0b06909f3..3c08103470 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,102 @@ -
+

FoxBox

-

Foxbox

- -
-
- -Foxbox is an integrated visualization and diagnosis tool for robotics, available in your browser or as a desktop app on Linux, Windows, and macOS. + Stars Badge + Forks Badge + Pull Requests Badge + Issues Badge + Version + GitHub contributors + License Badge +
+

+FoxBox is an integrated visualization and diagnosis tool for robotics, available in your browser or as a desktop app on Linux, Windows, and macOS. +

- Foxbox screenshot + Foxbox screenshot

-
-
+**Dependencies:** + +- [Node.js](https://nodejs.org/en/) v16.10+ +- [Git LFS](https://git-lfs.github.com/) -## Installation +
-Foxbox is can be ran locally as a web application by using the command (also available on package.json) +## :rocket: Getting started + +Clone the repository: ```sh -yarn run web:serve +$ git clone https://github.com/bmw-software-engineering/foxbox.git +``` + +Pull large files with Git LFS: + +```sh +$ git lfs pull +``` + +Enable corepack: + +```sh +$ corepack enable +``` + +Install packages from `package.json` : + +```sh +$ yarn install +``` + +- If you still get errors about corepack after running `corepack enable`, try uninstalling and reinstalling Node.js. Ensure that Yarn is not separately installed from another source, but is installed _via_ corepack. + +Launch the development environment: + +```sh +# To launch the desktop app (run both scripts concurrently): +$ yarn desktop:serve # start webpack +$ yarn desktop:start # launch electron + +# To launch the web app: +$ yarn run web:serve # it will be avaiable in http://localhost:8080 +``` + +## :hammer_and_wrench: Building FoxBox + +Build the application for production using these commands: + +```sh +# To build the desktop apps: +$ yarn run desktop:build:prod # compile necessary files + +- yarn run package:win # Package for windows +- yarn run package:darwin # Package for macOS +- yarn run package:linux # Package for linux + +# To build the web app: +$ yarn run web:build:prod + +# To build and run the web app using docker: +$ docker build . -t foxbox +$ docker run -p 8080:8080 foxbox + +# It is possible to clean up build files using the following command: +$ yarn run clean ``` -Foxbox will be accessible in your browser at [localhost:8080](http://localhost:8080/). -It can also be installed by using the desktop aplication versions available on [github releases](https://github.com/bmw-software-engineering/foxbox/tags). +- The desktop builds are located in the `dist` directory, and the web builds are found in the `web/.webpack` directory. -## Open Source +## :pencil: License (Open Source) Foxbox follows an open core licensing model. Most functionality is available in this repository, and can be reproduced or modified per the terms of the [Mozilla Public License v2.0](/LICENSE). -## Contributing +## :handshake: Contributing -Foxbox is written in TypeScript – contributions are welcome! -Note: All contributors must agree to our Contributor License Agreement. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details. +Contributions are welcome! FoxBox is primarily built in TypeScript and ReactJS. All potential contributors must agree to the Contributor License Agreement outlined in [CONTRIBUTING.md](CONTRIBUTING.md). -## Credits +## :star: Credits -Foxbox originally began as a fork of [FoxGlove Studio](https://github.com/foxglove/studio), an open source project developed by [Foxglove](https://app.foxglove.dev/). +FoxBox originally began as a fork of [FoxGlove Studio](https://github.com/foxglove/studio), an open source project developed by [Foxglove](https://app.foxglove.dev/). diff --git a/packages/studio-base/src/providers/CurrentLayoutProvider/defaultLayout.ts b/packages/studio-base/src/providers/CurrentLayoutProvider/defaultLayout.ts index c9856c3ba9..9546406ab1 100644 --- a/packages/studio-base/src/providers/CurrentLayoutProvider/defaultLayout.ts +++ b/packages/studio-base/src/providers/CurrentLayoutProvider/defaultLayout.ts @@ -8,8 +8,8 @@ import { defaultPlaybackConfig } from "@foxglove/studio-base/providers/CurrentLa /** * Overridden default layout that may have been provided when self-hosting via Docker * */ -const staticDefaultLayout = (globalThis as { FOXGLOVE_STUDIO_DEFAULT_LAYOUT?: LayoutData }) - .FOXGLOVE_STUDIO_DEFAULT_LAYOUT; +const staticDefaultLayout = (globalThis as { FOXBOX_STUDIO_DEFAULT_LAYOUT?: LayoutData }) + .FOXBOX_STUDIO_DEFAULT_LAYOUT; /** * This is loaded when the user has no layout selected on application launch diff --git a/packages/studio-web/src/webpackConfigs.ts b/packages/studio-web/src/webpackConfigs.ts index 7a569a2bb0..49a89d09b2 100644 --- a/packages/studio-web/src/webpackConfigs.ts +++ b/packages/studio-web/src/webpackConfigs.ts @@ -172,7 +172,7 @@ export const mainConfig =
diff --git a/resources/screenshot.png b/resources/screenshot.png index 02df1e2e6e..0f79bbeffc 100644 --- a/resources/screenshot.png +++ b/resources/screenshot.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:5c6765fd2c8d56d1c21cb70a3609a1aa4edc866500f620f7a8dee5878906ede1 -size 4146190 +oid sha256:1471a4829aeec48a0716680920f518bef39c0957909f94e23b19c6b5dffd6f76 +size 3898646