Merge pull request #352 from Chia-Network/update-v2-readme

chore: update README.md

README.md

@@ -1,90 +1,128 @@
-# Carbon UI Template
-
-This repo contains the base architecture for a robust client rendered single page application built on React JS and typescript.
-Applications built on this template can be packaged into electron applications. Other base technologies used are
-Vite JS, Redux Tool Kit, RTKquery and Flowbite-React. The application has a left navigation bar listing pages to be
-navigated to.
-
-### General
-The app resides almost entirely in src/renderer. main.ts exists only to start the electron process and open a window
-requesting the site from the vite server. Exports within the renderer directory are exported from the directory in
-which they reside via index.ts files up to the respective top level folder in the renderer directory. Imports are handled
-by importing from @/top-level-dir. for instance to import foo which resides in directory components/fuz/baz, merely import 
-from @/components. When exporting via the established pattern, there is no need for relative imports. 
-
-The left navigation bar's buttons are hooked up to the react-router which handles page navigation. the router resides
-in routes/AppNavigator.tsx and the page paths exist in route-constants.ts
-
-### API Calls
-API calls are handled via RTKquery, whose base configuration resides in /api/cadt/v1/index.js. It is recommended to
-retain this directory structure and configuration as it allows for dynamic host configuration which is already baked
-into this template. The 'cadt' directory can be renamed to whatever is appropriate.
-endpoints are defined in the /v1 directory alongside index.ts. 
-
-The endpoints define hooks which mutate or query their resources. There are 2 illustrative examples of how to 
-define RTKQuery endpoints in the /v1 directory. Note that when exporting a hook from an endpoint, the name to export 
-is prepended with use, and appended with either query or mutation. To export resource query hook foo, the export name 
-will need to be useFooQuery. For mutation hook foo it will need to be useFooMutation. 
-
-projects.api.ts can be deleted as it is only use in other sample code that will be deleted, but it is highly
-recommended that system.api.ts be kept and the resource url's changed to the /health equivalent for the backend the
-app will be connected to. the application uses these system hooks to determine if the backend is available or not.
-removing it will require refactoring, and it will likely end-up being reimplemented over the course of development.
-
-### Components
-Please see the next section on theming details and implementation
-
-This UI is built on Flowbite-React tailwind CSS components. Flowbite component theming is handled by importing the 
-flowbite components into /components/proxy, then re-exporting the components with a flowbite theme applied. 
-If a component needs to be themed, the theme should be declared and set in the proxy component. Page and
-component layouts are achieved via tailwind CSS (with few exceptions). It is recommended to keep it that way. The style
-prop is only set in circumstances when tailwind classes would not suffice. Flowbite components should only be imported
-via @/components. Importing directly from flowbite will introduce inconsistent theming since the theming is set in the
-/components/proxy components. Note that there is a theme selector component which toggles between the tailwind defined 
-light mode and dark mode provided by flowbite.
-
-Forms are handled with formik. the forms themselves can be found in components/blocks/forms and prebuild form components
-can be found in components/form.
-
-### Theme
-Preface - Flowbite-React Documentation: https://flowbite-react.com/docs/components/accordion (See component list in left nav)
-
-The Flowbite component library is built on tailwind css classes, but in most cases the components will not react to a
-class or classname being set. To customize the appearance of a flowbite component, a theme will need to be set on the
-component (see the next section on where to do this in the codebase). In the flowbite documentation at the bottom of each component page the theme
-that defines the component is provided. The theme is an object with each prop representing a sub-component of the component to
-style and the value being a string of the tailwind classes that define the component. When styling a component the entire tailwind string
-should be copied, and generally only colors should be changed. At the time of writing any color prefaced with dark: should
-NOT be changed. Additionally, colors should only be changed if they're set from the global custom colors. More in the next 
-paragraph. An example theme can be found in components/proxy/sidebar.tsx
-
-Global theme colors are provided via an optional colors.json file that the app attempts to fetch. if it exists, the colors
-are set via global css properties defined in App.css. To define new colors, the new color must be defined in:
-- App.css
-- tailwind.config.js
-- colors.json
-
-From there the color CSS property should be declared in the components that need to apply it.
-
-### Patterns
-The sample patterns in this application are what allow it to be so robust. There are 2 general patterns employed, one
-pattern for displaying data and another pattern for initiating backend operations (or anything else). 
-The pattern for displaying data has 3 general steps:
-- the data is fetched with RTKquery hooks at the page level, and all display and organization options are set
-- the data and options are passed to a data organization component which defines the structure and configuration
-of how to display the data
-- the structure, data, and options are passed to a common base component responsible for rendering the data
-
-This pattern is exemplified by pages/TokensPage.tsx, components/blocks/tables/ProjectsListTable.tsx, and 
-components/layout/Datatable.tsx. TokensPage.tsx fetches the data via the RTKQuery hooks, then passes the data,
-filters, and sorts to ProjectsListTable.tsx, which defines the structure (columns) of the table and passes the structure and data
-down to the generalized DataTable.tsx. The project table and data table are directly controlled at the page level and
-make no assumptions about the data or how to display it. The data table can be used in any capacity for any table and
-any data set.
-
-For all other operations that don't involve fetching and sorting data, a pattern of self-contained components which
-pull date directly from the api hooks and are parent component-agnostic is used. Prop drilling is explicitly avoided.
-
-For deep-linking components and state, the hooks/ directory contains hooks for manipulating query params and url hashes.
-these hooks operate much like the useState hook with additional arguments. pages/TokensPage.tsx has examples for
-how to use these hooks.
+# Climate Tokenization Engine User Interface
+
+User interface for the [Climate Tokenization Engine](https://github.com/Chia-Network/Climate-Tokenization-Engine).  
+Intended to be run as a desktop application and connect to
+the [Climate Tokenization Engine](https://github.com/Chia-Network/Climate-Tokenization-Engine)
+API running either locally or remotely.
+
+## Related Projects
+
+* [Chia Blockchain](https://github.com/Chia-Network/chia-blockchain)
+* [Climate Tokenization Engine](https://github.com/Chia-Network/Climate-Tokenization-Engine)
+* [Climate Explorer](https://github.com/Chia-Network/climate-token-driver)
+* [Chia Climate Tokenization](https://github.com/Chia-Network/climate-token-driver)
+* [Climate Explorer UI](https://github.com/Chia-Network/climate-explorer-ui)
+* [Climate Wallet](https://github.com/Chia-Network/Climate-Wallet)
+* [Climate Action Data Trust](https://github.com/Chia-Network/cadt)
+* [Climate Action Data Trust UI](https://github.com/Chia-Network/cadt-ui)
+
+## Installation
+
+Packages are available for Windows, Mac, and Debian-based Linux distribution on the
+[releases](https://github.com/Chia-Network/Climate-Tokenization-Engine-UI/releases) page.
+
+### Using APT on Debian-based Linux Distros (Ubuntu, Mint, etc)
+
+The Climate Tokenization Engine UI can be installed with `apt`.
+
+1. Start by updating apt and allowing repository download over HTTPS:
+
+```
+sudo apt-get update
+sudo apt-get install ca-certificates curl gnupg
+```
+
+2. Add Chia's official GPG Key (if you have installed Chia with `apt`, you'll have this key already and will get a
+3. message about overwriting the existing key, which is safe to do):
+
+```
+curl -sL https://repo.chia.net/FD39E6D3.pubkey.asc | sudo gpg --dearmor -o /usr/share/keyrings/chia.gpg
+```
+
+3. Use the following command to setup the repository.
+
+```
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/chia.gpg] https://repo.chia.net/climate-tokenization/debian/ stable main" | sudo tee /etc/apt/sources.list.d/climate-tokenization.list > /dev/null
+```
+
+4. Install the Climate Tokenization Engine UI
+
+```
+sudo apt-get update
+sudo apt-get install climate-tokenization-engine-ui
+```
+
+5. Run the Climate Explorer UI from your OS launcher or at the command line with `climate-tokenization-engine-ui`.
+
+## Developer Guide
+
+### Installation From Source
+
+```sh
+git clone [email protected]:Chia-Network/climate-explorer-ui
+cd climate-explorer-ui
+nvm install
+nvm use
+npm install -g husky
+npm install -g prettier
+npm install -g lint-staged
+npm install -g git-authors-cli
+
+npm run start
+```
+
+#### Prerequisites
+
+You'll need:
+
+- Git
+- [nvm](https://github.com/nvm-sh/nvm)
+
+This app uses `nvm` to align node versions across development, CI and production. If you're working on Windows you
+should consider [nvm-windows](https://github.com/coreybutler/nvm-windows)
+
+### Contributing
+
+Upon your first commit, you will automatically be added to the package.json file as a contributor.
+
+#### Commiting
+
+[Signed commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
+are required.
+
+This repo uses a commit convention. A typical commit message might read:
+
+```
+    fix: correct home screen layout
+```
+
+The first part of this is the commit "type". The most common types are "feat" for new features, and "fix" for bugfixes.
+Using these commit types helps us correctly manage our version numbers and changelogs. Since our release process
+calculates new version numbers from our commits it is very important to get this right.
+
+- `feat` is for introducing a new feature
+- `fix` is for bug fixes
+- `docs` for documentation only changes
+- `style` is for code formatting only
+- `refactor` is for changes to code which should not be detectable by users or testers
+- `perf` is for a code change that improves performance
+- `test` is for changes which only touch test files or related tooling
+- `build` is for changes which only touch our develop/release tools
+- `ci` is for changes to the continuous integration files and scripts
+- `chore` is for changes that don't modify code, like a version bump
+- `revert` is for reverting a previous commit
+
+After the type and scope there should be a colon.
+
+The "subject" of the commit follows. It should be a short indication of the change. The commit convention prefers that
+this is written in the present-imperative tense.
+
+#### Commit linting
+
+Each time you commit the message will be checked against these standards in a pre-commit hook. Additionally all the
+commits in a PR branch will be linted before it can be merged to master.
+
+#### Branch Layout
+
+All pull requests should be made against the `develop` branch. Commits to the `main` branch will trigger a release,
+so the `main` branch is always the code in the latest release.