Contributing
Making a code contribution might seem intimidating, but it’s not too difficult:
- Make a fork of the WebODM repository
- Clone your repository in a directory
- Create a new branch:
git checkout -b branchname. - Setup a development environment with docker.
- Commit the changes:
git commit -a -m "describe your changes" - Push the changes to your repository:
git push origin branchname - Create a pull request
We don’t have many rules. Follow the guidelines indicated in the Contributing document, be nice to others and you’ll do great! :)
Setup a Development Environment
Section titled “Setup a Development Environment”Follow the WebODM docker installation instructions, then run:
./webodm.sh start --dev
That’s it! You can modify any of the files, including SASS and React.js files. Changes will be reflected in the running WebODM instance automatically.
Run Unit Tests
Section titled “Run Unit Tests”We think testing is a necessary part of delivering robust software. We try to achieve complete test coverage for backend code and at a minimum robust smoke testing for frontend code.
To run the unit tests, simply type:
./webodm.sh test
Apply Changes In Production
Section titled “Apply Changes In Production”Once you’re done making changes, if you start WebODM in production mode (without the --dev flag), you will notice that your changes are missing. This is because webodm.sh uses the opendronemap/webodm_webapp docker image to launch WebODM, which doesn’t have your changes. To apply the changes, you need to rebuild the docker image locally:
docker build -t opendronemap/webodm_webapp .
You can also modify the docker-compose.yml file to point to a different image.
Project Overview
Section titled “Project Overview”Backend
Section titled “Backend”The backend is based mainly on Django and Django REST Framework.
We don’t use much of Django’s templating system, except for the Administration and Processing Nodes sections. Instead we use Django to expose an API, which we then tie to a React.js app.
Directories of interest are listed as follow:
| Directory | Description |
|---|---|
/app | Main application, includes the UI components, API, tests and backend logic. |
/nodeodm | Application that bridges the communication between WebODM and NodeODM. Includes its own unit tests and models. |
/webodm | Django’s main project directory. Setting files are here. |
Frontend
Section titled “Frontend”We use a React.js app (ES6 syntax) and SCSS for various UI components such as the dashboard. We use webpack to build intermediate components into a static bundle.
Directories of interest are listed as follow:
| Directory | Description |
|---|---|
/app/templates/app | Location of Django templates. While we don’t use them a lot, we use them for a few pages and as a glue to bootstrap the React code. |
/app/static/app/js | Location of Javascript files for all UI components. |
/app/static/app/js/components | We try to separate components for reusability into various React components. Each component is stored here. |
/app/static/app/js/css | Each component should have its own SCSS file. Those files are stored here. |
/app/static/app/js/main.jsx is the entry point for the UI. If you wonder how we tie Django and React.js together, this is the file to look at to begin your search.
Documentation
Section titled “Documentation”We use Astro to generate our documentation. See their project’s documentation for information about making changes to the documentation.