The Admin Panel is the part of the Treetracker project for verifying, processing and managing data collected by the Treetracker app.
This is the React web frontend of the Admin Panel, built with create-react-app and Material UI.
The legacy Admin Panel API is managed separately under Greenstand/treetracker-admin-api. The API specification is (partially) documented in OpenAPI format: treetracker-admin.v1.yaml
The Admin Panel project is in the process of migrating away from a single, dedicated API to use the latest Greenstand microservices, including:
- Greenstand/treetracker-api
- Greenstand/treetracker-earnings-api
- Greenstand/treetracker-field-data
- Greenstand/treetracker-query-api
- Greenstand/treetracker-regions-api
- Greenstand/treetracker-reporting
- Greenstand/treetracker-stakeholder-api
The spec for each of these APIs can be found in the docs/api/spec directory of each project.
Please add any missing content to this readme as a pull request.
There are three main options for development in the Admin Panel:
- For frontend work only (recommended):
- Follow the steps below to fork and clone this repo
- For API work only:
- Follow setup instructions in the treetracker-admin-api project
- As a completely local development environment (not normally required):
- Install postgres and postgis locally, install a database seed, and run database migrations
- Install and run the backend API, configured to use your local database
- Install and run the frontend, configured to user you local backend API
See https://git-scm.com/downloads for instructions.
We recommend using nvm to install and manage your Node.js instances. More details here: https://www.sitepoint.com/quick-tip-multiple-versions-node-nvm/
- Make sure a profile exists for your terminal, run
touch ~/.profile; touch ~/.zshrc
- Install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
- Install the latest version of Node.js 18:
nvm install 18
- Use the installed Node.js:
nvm use 18
Alternatively, you can install Node.js directly from https://nodejs.org/dist/latest-v18.x/
On MacOS, you can alleviate the need to run as sudo by using nvm or by following John Papa's instructions.
- Click Fork on this GitHub repo and follow the steps to fork the repo to your account
- Open terminal
- Go to a folder where you would like to install the project. Then type the following, replacing
<username>
with your GitHub username:
git clone https://github.com/<username>/treetracker-admin-client
Move into the new source code directory and add Greenstand as a remote:
cd treetracker-admin-client
git remote add upstream https://github.com/Greenstand/treetracker-admin-client
Only required if you are also developing and running the backend/API locally
- Add a
.env.local
file in the root directory containing the following line:
REACT_APP_API_ROOT=http://localhost:3000
npm install
npm start
Visit http://localhost:3001
Valid login credentials for the Admin Panel within the development environment can be found pinned to the #admin_panel_chat channel in Slack.
Ask for channel access in #engineering
channel
- Look through the open issues for one that looks interesting. Use labels to look for good first issues, or to filter by size: you could start small, or get your teeth into something more substantial (medium or large).
- If you're not sure what to work on, ask in the #admin_panel_chat channel on Slack and we'll find a good issue for you.
- Add a comment to the selected issue to say you'd like to work on it, and ask for any clarification you need. Some of the info you need to solve the problem may be missing from the description of the issue.
- One of the Greenstand leads will then assign it to you and try to help with any questions.
There are lots of opportunities to offer ideas and take ownership of larger pieces of work, so don't be afraid to ask!
- Create a branch for the issue in your local repo
- Make your changes and test everything works locally
- Push your changes to your fork on GitHub and create a pull request into Greenstand/master
- Fill in as much info as you can in the PR, including screenshots or videos of the change to help the reviewer understand what you've done
- A member of the review team will review your changes (it can take a little while, since lots of us are volunteers) and may request changes
- Make the requested changes, asking for clarification in the PR if necessary, and push the updated code
- When the reviewer is happy, they will approve and merge your changes
You can work one more than one issue at a time, while you wait for your PR to be reviewed or questions to be answered, but remember to keep each issue on a separate branch. If two issues are closely related, you can combine them in one branch and PR.
We use automatic semantic versioning, which looks at commit messages to determine how to increment the version number for deployment.
Your commit messages will need to follow the Conventional Commits format, for example:
feat(account): add new button
Since we squash commits on merging PRs into master
, this applies to PR titles as well.
Your forked repo won't automatically stay in sync with Greenstand, so you'll need to occassionally sync manually (typically before starting work on a new feature).
git checkout master
git pull upstream master --rebase
git push origin master
If there are merge conflicts in your PR, you may need to rebase your branch. Ask a member of the team if you need help with this.
git checkout <feature_branch>
git pull upstream master --rebase
git push origin <feature_branch> --force
We follow the Airbnb JavaScript style guide. The superficial aspects of this style are enforced by a pre-commit hook in the project that runs Prettier when you commit a change.
If you are using VSCode as your IDE, please follow this guide to set up Prettier and automatically format your code on file save.
You can also manually run npm run prettier
. Configuration files are already included in this repo.
Indention 2 Spaces for indentation
Semicolon Use semicolons at the end of each line
Characters 80 characters per line
Quotes Use single quotes unless you are writing JSON
const foo = 'bar';
Braces Opening braces go on the same line as the statement
if (true) {
console.log('here');
}
Variable declaration Declare one Variable per statement
const dog = ['bark', 'woof'];
let cat = ['meow', 'sleep'];
Variable, properties and function names Use lowerCamelCase for variables, properties and function names
const adminUser = db.query('SELECT * From users ...');
Class names Use UpperCamelCase for class names
class Dog {
bark() {
console.log('woof');
}
}
Descriptive conditions Make sure to have a descriptive name that tells the use and meaning of the code
const isValidPassword =
password.length >= 4 && /^(?=.*\d).{4,}$/.test(password);
Object/Array creation Use trailing commas and put short declarations on a single line. Only quote keys when your interpreter complains:
var a = ['hello', 'world'];
var b = {
good: 'code',
'is generally': 'pretty',
};
We follow the React/Jest convention for writng tests. All test file are located at the same directory with the file under test, named xxx.test.js
.
Please ensure that at least all the model unit tests under ./src/model/
pass.
To run tests:
npm test
Make your own /cypress/fixtures/login.json
file containing the actual credentials in order to run the cypress tests.
We use loglevel for logging, with some conventions. Using loglevel, we will be able to open/close a single file's log by chaining the level of log on the fly, even in production env.
The default of log level is set in the file: ./src/init.js
log.setDefaultLevel('info');
To use loglevel in js file, we recommend following this convention:
import * as loglevel from 'loglevel'
const log = loglevel.getLogger('../components/TreeImageScrubber')
... ...
log.debug('render TreeImageScrubber...')
The convention is: call the loglevel.getLogger()
function with argument of 'the path to current file'. In the above example, the js file is: /src/components/TreeImageScrumbber.js
, so pass the path string: ../components/TreeImageScrubber
in, just like what we do in 'import' statement, but the path just points to itself.
Actually, we can pass in any string, following this convention is just for a UNIQUE key for the log object, now we can set the log level in browser to open/close log. To do so, open DevTools -> application -> localstorage -> add a key: 'loglevel:[the path]' and value: [the log level] (e.g. loglevel:../components/TreeImageScrubber -> DEBUG )
We use Material-UI (4.0 currently) to build our UI.
We made some custom by setting the theme of Material-UI to fit our UI design. The customized theme file is located at ./src/components/common/theme.js
. If you find components do not work as you expect, please check section: overrides and props in theme, we override some default styles and behaviors.
We create some basic components, such as 'alert', 'confirm', 'form', feel free to pick what you want or copy the sample code. You can find them in our Storybook components gallery.
You can also pick the typographies and colors as you want in Storybook -> MaterialUITheme -> theme/typography/palette.
We use Storybook to develop/test components independently.
Run the following command to start Storybook:
npm run storybook
Visit this URL in the browser: http://localhost:9009
All the stories are located at ./src/stories/
- Modify
.releaserc.json
by adding new branch and channel into thebranches
array:
...
{
"name": "feature1",
"prerelease": true,
"channel": "beta"
},
...
- Create a new branch, for example:
git remote add greenstand git@github.com:Greenstand/treetracker-admin-client.git
git checkout greenstand/master
git checkout -b feature1
git push greenstand feature1
- Push commit to the branch:
The new push will trigger the first release of this branch with tag/version: v1.2.3-feature1.1
, and release to http://dev-beta-admin.treetracker.org, and following commits will update/increase the last version number, which is 1
here.
Normal merge from freature1
to master
will trigger the recalculate of the version, for example: if master
is on v2.0.0
, then the merge will add all changes from feature1
to add to the version of master.
Now supported channls and domain for dev and prod respectively:
- master: dev-admin.treetracker.org admin.treetracker.org
- beta: dev-beta-admin.treetracker.org beta-admin.treetracker.org
- alpha: dev-alpha-admin.treetracker.org alpha-admin.treetracker.org
- freetown: dev-freetown-admin.treetracker.org freetown-admin.treetracker.org
.