Skip to content

Latest commit

 

History

History
119 lines (94 loc) · 7.88 KB

CONTRIBUTING.md

File metadata and controls

119 lines (94 loc) · 7.88 KB
Raw

Contributing to Biophonie

We welcome contributions to this project.

If you would like to suggest a new feature or report a bug, fill the provided template when creating an issue and take a look at the contributing section.

If you would like to contribute code:

  1. Please note that any contribution should follow the code of conduct
  2. Please familiarize yourself with the install process, the development process and the deployment at the bottom of this document. All contributions to the project must reflect its development standards. As such, respect of ktfmt and detekt is required.
  3. Ensure that existing pull requests and issues don’t already cover your contribution or question. If your planned contribution involves significant changes to the application, consider opening a new issue to discuss your design before beginning work.
  4. Pull requests are gladly accepted. If your PR makes changes that developers should be aware of, please be sure to update the CHANGELOG
  5. When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.

Build locally

Prerequisite

The Biophonie application heavily relies on Mapbox SDK. Thus, building this repository requires to have an account on Mapbox.

Setting up the repository

Clone the git repository:

$ git clone [email protected]:DesignandHuman/biophonie.git

Using soundwave

Soundwave is a library used to play and record sounds in the shape of wave forms. It is mandatory to build it alongside Biophonie so, you will need to clone the repository:

$ git clone [email protected]:Haransis/WaveFormPlayer.git

Then you will need to set the Soundwave Directory.

Note 🚧 : In the future, this dependency will be made available in a Maven Repository.

Configuring the project

Before building, the project needs to be configured. A couple of configurations need to be in place before a successful build and test run can be made. Define the following environment variables in the global Gradle Properties (located in $USER_HOME/.gradle/gradle.properties). The following steps describe how to define the related environmental variables needed to build the project:

Mapbox Download Token

The MAPBOX_DOWNLOAD_TOKEN is a Mapbox access token, used during compile time, with a scope set to DOWNLOADS:READ. This token allows to download all required Mapbox dependencies from a Mapbox Maven instance. The DOWNLOADS:READ scope can be set when creating a new access token on https://account.mapbox.com/. The token configuration can be found in the root build.gradle.kts of the project.

Mapbox Access token

The MAPBOX_ACCESS_TOKEN is a mapbox access token, packaged as part of test application, to load Mapbox tiles and resources. This token can be configured on https://account.mapbox.com/ and doesn't require any specific scopes.

Mapbox style URL

The STYLE_URL is a URL pointing to a mapbox style. It is of the form: mapbox://styles/OWNER/HASH The style used in the production app is based upon the creation of Geoffrey Dorne but you can use any style such as a standard one: mapbox://styles/mapbox/light-v11.

Soundwave Directory

The SOUNDWAVE_DIR is the path to the directory containing the soundwave library. It can be found in the WaveFormPlayer repository (see also Installing the dependency).

Debug API URL

This BIOPHONIE_DEBUG_API_URL is a URL pointing to the external API you want to use for debug version (see Communicate with the remote API to learn how to use your own). The API is needed to find geolocated sounds, record and upload them. You can find the code of the api here.

example global gradle.properties

MAPBOX_DOWNLOAD_TOKEN=sk.eyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MAPBOX_ACCESS_TOKEN=pk.eyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BIOPHONIE_STYLE_URL=mapbox://styles/user/xxxxxxxxxxxxxxxxxxxxx
SOUNDWAVE_DIR=/home/user/AndroidStudioProjects/WaveFormPlayer/soundwave
# use a local instance of biophonie-api from an emulator
BIOPHONIE_DEBUG_API_URL=http://10.0.2.2:8080

Communicate with the remote API

The production API is located at https://biophonie.fr/. The preproduction API will be soon available (track progress here). To do your own testing, please clone the biophonie-api repository and launch your own instance of it using docker.

Checks

A precommit hook checks for the respect of ktfmt and detekt. Automatic formatting is done using the command:

$ ./gradlew ktfmtFormat

You can add exceptions to detekt with: app/detekt-baseline.xml or with @SupressWarnings("RULENAME"). :warning: Beware, changes that do not justify any exception to linters will be automatically rejected.

Other than that, the project do not have any testing implemented yet (track progress here). In the meantime, you should test your modifications by hand.

Architecture

The project follows the recommended Android architecture guidelines and especially the type of modules described here. Module dependency graphs are available in the README of each module. If architecture changes are required, execution of scripts/generateModuleGraphs.sh regenerates the corresponding graphs.

Commit

This repository follows the gitmoji convention. A commit title should start with an emoji. See the website or use the gitmoji-cli to find the adequate emoji. Here are the main emojis that should be used but feel free to use the ones listed that fit better your needs:

  • ✨ : new feature
  • 💄 : ui change
  • ♻️ : refactoring
  • 🐛 : bug fix
  • 📝 : documentation change

Next is a sentence starting with a verb starting with a minuscule letter and ending without any dot. The title should be as precise as possible.

Optionnaly, a commit message can be added. It should tell a story about the what, how and why a change is happening. It can also contain the issue that it solves.

Wrong commit title Fix issue with crash of application.

Correct commit title :bug: init imageUri to prevent NullPointerEx

Pull Requests

Pull requests should follow the corresponding template. Their title should follow the same convention as the commits.