Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix/6209 comment reset on mouse drag outside popup #46

Merged
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
bbead62
Merge pull request #6196 from varun2948/feat-osm-download
kshitijrajsharma Jan 12, 2024
ad07d71
Update working-groups.md
petya-kangalova Jan 16, 2024
2178491
Merge pull request #6201 from hotosm/petya-kangalova-patch-1
robsavoye Jan 16, 2024
8bd18af
fix: Move working-groups to docs after it got updated
robsavoye Jan 16, 2024
94922d7
fix: Add updated docs from docs-old
robsavoye Jan 16, 2024
c89b745
fix: Fix link to images
robsavoye Jan 16, 2024
60981d8
fix: Move error_code.md to developers, migration.md to sysadmin
robsavoye Jan 16, 2024
a69e9ed
fix: Remove erd.md
robsavoye Jan 16, 2024
72a74ee
fix: Delete old images that have been replace by the new diagrams
robsavoye Jan 16, 2024
1558f47
fix: Remove doc that was already migrated and updated in docs
robsavoye Jan 16, 2024
2eb01d5
Merge pull request #6203 from robsavoye/diagrams
robsavoye Jan 18, 2024
69046d7
fix: Fix relative links, add new docs to the menu
robsavoye Jan 18, 2024
e0a3d7a
Merge pull request #6206 from robsavoye/develop
robsavoye Jan 18, 2024
415ac65
Merge pull request #6205 from varun2948/feat-osm-download
kshitijrajsharma Jan 18, 2024
190649a
fix: Add dataflow page for diagrams
robsavoye Jan 22, 2024
af43bd7
Merge branch 'develop' of github.com:robsavoye/tasking-manager into d…
robsavoye Jan 22, 2024
131cdc1
fix: Fix links to docs
robsavoye Jan 22, 2024
60b5535
fix: For now make the index the about page
robsavoye Jan 22, 2024
127ae82
fix: Adjust links for docs that got moved to developers directory
robsavoye Jan 22, 2024
cbfbf57
fix: Fix links to images
robsavoye Jan 22, 2024
6639908
fix: Adjust links for docs that got moved to developers directory
robsavoye Jan 22, 2024
4c6fb8d
fix: Use hard word wrap for test editors
robsavoye Jan 22, 2024
7429a99
fix: Move some docs to developers, add deep tech dive section
robsavoye Jan 22, 2024
6147ada
Merge pull request #6215 from robsavoye/develop
robsavoye Jan 22, 2024
03a4a0f
Fix popup close issue on mouse drag outside popup in `TaskActivityDet…
royallsilwallz Jan 19, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -12,8 +12,8 @@ This is Free and Open Source Software. You are welcome to use the code and set u

## Get involved!

* Start by reading our [Code of conduct](https://github.com/hotosm/tasking-manager/blob/develop/docs/code_of_conduct.md)
* Get familiar with our [contributor guidelines](https://github.com/hotosm/tasking-manager/blob/develop/docs/contributing.md) explaining the different ways in which you can support this project! We need your help!
* Start by reading our [Code of conduct](docs/developers/code_of_conduct.md)
* Get familiar with our [contributor guidelines](docs/developers/contributing.md) explaining the different ways in which you can support this project! We need your help!
* Join the Tasking Manager Collective Meet up - an opportunity to meet other Tasking Manager contributors. The meet ups take place on the second Wednesday of the month at 9:00 or 15:00UTC! Register to receive a calendar invite: https://bit.ly/3s6ntmV or join directly via this link: https://meet.jit.si/TaskingManagerCollectiveMeetUp
* Read the monthly update blogs on [OSM Discourse](https://community.openstreetmap.org/c/general/38/all).

1 change: 0 additions & 1 deletion docs-old/assets/TM ERD.drawio

This file was deleted.

4 changes: 0 additions & 4 deletions docs-old/assets/Tasking Manager.svg

This file was deleted.

Binary file removed docs-old/assets/osm-oauth-settings.jpg
Binary file not shown.
Binary file removed docs-old/assets/project-view.gif
Binary file not shown.
5 changes: 0 additions & 5 deletions docs-old/erd.md

This file was deleted.

54 changes: 0 additions & 54 deletions docs-old/migration.md

This file was deleted.

182 changes: 0 additions & 182 deletions docs-old/review-pr.md

This file was deleted.

268 changes: 0 additions & 268 deletions docs-old/setup-development.md

This file was deleted.

24 changes: 0 additions & 24 deletions docs-old/working-groups.md

This file was deleted.

40 changes: 23 additions & 17 deletions docs/about.md
Original file line number Diff line number Diff line change
@@ -4,29 +4,35 @@
[![TM Backend on Quay](https://quay.io/repository/hotosm/tasking-manager/status "Tasking Manager Backend Build")](https://quay.io/repository/hotosm/tasking-manager)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=hotosm_tasking-manager&metric=alert_status)](https://sonarcloud.io/dashboard?id=hotosm_tasking-manager)

[<img src="images/screenshot.jpg" />](images/screenshot.jpg)

The most popular tool for teams to coordinate mapping on OpenStreetMap. With this web application, an area of interest can be defined and divided up into smaller tasks that can be completed rapidly. It shows which areas need to be mapped and which areas need a review for quality assurance. You can see the tool in action: log into the widely used [HOT Tasking Manager](https://tasks.hotosm.org/) and start mapping.

This is Free and Open Source Software. You are welcome to use the code and set up your own instance. The Tasking Manager has been initially designed and built by and for the [Humanitarian OpenStreetMap Team](https://www.hotosm.org/), and is nowadays used by many communities and organizations.
![<img src="images/screenshot.jpg" />](images/screenshot.jpg)

The most popular tool for teams to coordinate mapping on
OpenStreetMap. With this web application, an area of interest can be
defined and divided up into smaller tasks that can be completed
rapidly. It shows which areas need to be mapped and which areas need a
review for quality assurance. You can see the tool in action: log into
the widely used [HOT Tasking Manager](https://tasks.hotosm.org/) and
start mapping.

This is Free and Open Source Software. You are welcome to use the code
and set up your own instance. The Tasking Manager has been initially
designed and built by and for the [Humanitarian OpenStreetMap
Team](https://www.hotosm.org/), and is nowadays used by many
communities and organizations.

## Get involved!

* Start by reading our [Code of conduct](https://github.com/hotosm/tasking-manager/blob/develop/docs/code_of_conduct.md)
* Get familiar with our [contributor guidelines](https://github.com/hotosm/tasking-manager/blob/develop/docs/contributing.md) explaining the different ways in which you can support this project! We need your help!
* Join the Tasking Manager Collective Meet up - an opportunity to meet other Tasking Manager contributors. The meet ups take place on the second Wednesday of the month at 9:00 or 15:00UTC! Register to receive a calendar invite: https://bit.ly/3s6ntmV or join directly via this link: https://meet.jit.si/TaskingManagerCollectiveMeetUp
* Join a Tasking Manager [working group](working-groups.md)
* Start by reading our [Code of conduct](developers/code_of_conduct.md)
* Get familiar with our [contributor guidelines](developers/contributing.md)
explaining the different ways in which you can support this project!
We need your help!
* Read the monthly update blogs on [OSM Discourse](https://community.openstreetmap.org/c/general/38/all).

## Product Roadmap
We have included below a [high level roadmap/plan](https://github.com/orgs/hotosm/projects/28/) [subject to change] that can be used as an overview.


## Developers

* [Understand the code](./docs/developers/understanding-the-code.md)
* [Setup the TM for development](./docs/developers/development-setup.md)
* [Learn about versions and releases](./docs/developers/versions-and-releases.md)
* Help us and submit [pull requests](https://github.com/hotosm/tasking-manager/pulls)
We have included below a [high level
roadmap/plan](https://github.com/orgs/hotosm/projects/28/) [subject to
change] that can be used as an overview.

## Instances
* [HOT Tasking Manager (production)](https://tasks.hotosm.org)
64 changes: 64 additions & 0 deletions docs/dataflow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Tasking Manager Dataflow

## Activity

The Tasking Manager has several user data flows, as there are
differences between a project manager, a mapper, and a validator as
seen in this diagram.

<a href="images/activity.png">
![Activity](images/activity.png){ width=30%,height:30px }</a>

Initially most Tasking Manager projects start with a disaster
notification. The activation team discusses the notification, and if a
response is needed creates a project. The project is an Area Of
Interest (AOI) as a polygon, and a description and instructions. Then
the AOI is split into tasks.

Then when the project is announced, mappers select a task, and map the
desired features for the project. Once the complete a task, it's
marked as mapped, and then the mapper can select another task, and so
on.

Then the validator reviews all the tasks marked as mapped. There is
more information on the [Validation process](validation.md) at this
link.

# Solution User

<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/solution-user.png">
![Solution User](images/solution-user.png){ width=30%,height:30px }</a>

## Component

The Tasking Manager has multiple components. WHat the user sees is the
REACT based frontend in their browser.
<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/component.png">
![Component](images/component.png){ width=40%,height:30px }</a>

The backend for the Tasking Mamnager is written using Flask, which is
in python. This supplies the REST API, which the frontend uses. This
API is also open to other projects.

The data of course is OpenStreetMap, which is stored in a postgres
database.

## Conceptual

The Tasking Manager uses other projects for some of it's data needs of
the backend. This includes Oshome for mapping statistics, the HOT raw
data API for data extracts, and OpenStreetMap of course.

<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/conceptual.png">
![Conceptual](images/conceptual.png){ width=30%,height:30px }</a>

# Information Flow

This diagram shows the other projects that the Tasking Manager
exchanges informstion with. OpenStreetNap(OSM) of course supplies
data, and data from Tasking Manager projects goes into
OSM. OpenAerialMap may be used as a source of imagery. Also projects
may be transfered thh the Field Mapping Tasking Manager(FMTM).

<a href="https://raw.githubusercontent.com/hotosm/tasking-manager/develop/docs/images/information_flow.png">
![Information Flow](images/information_flow.png){ width=30%,height:30px }</a>
File renamed without changes.
4 changes: 2 additions & 2 deletions docs/contributing.md → docs/developers/contributing.md
Original file line number Diff line number Diff line change
@@ -59,7 +59,7 @@ testing, please comment on the PR directly.

Create pull requests (PRs) for changes that you think are needed. We
would really appreciate your help! We ask that you follow our [coding
contribution guidelines](developers/contributing-guidelines.md)
contribution guidelines](contributing-guidelines.md)

Skills with the following would be beneficial:

@@ -76,7 +76,7 @@ Our latest task board can be found
## Translating

Review or submit [language
translations](developers/translations.md). Translations are important
translations](translations.md). Translations are important
as it makes Tasking Manager more efficient when it supports local
languages.

104 changes: 77 additions & 27 deletions docs/developers/development-setup.md
Original file line number Diff line number Diff line change
@@ -57,7 +57,9 @@ To learn React, check out the [React documentation](https://reactjs.org/).

### Backend

The backend is made up of a postgres database and an associated API that calls various end points to create tasks, manage task state, and produce analytics.
The backend is made up of a postgres database and an associated API
that calls various end points to create tasks, manage task state, and
produce analytics.

#### Dependencies

@@ -67,15 +69,22 @@ The backend is made up of a postgres database and an associated API that calls v
* [pip](https://pip.pypa.io/en/stable/installing/)
* [libgeos-dev](https://trac.osgeo.org/geos/)

You can check the [Dockerfile](../scripts/docker/tasking-manager/Dockerfile) to have a reference of how to install it in a Debian/Ubuntu system.
You can check the
[Dockerfile](https://github.com/hotosm/tasking-manager/blob/develop/Dockerfile)
to have a reference of how to install it in a Debian/Ubuntu system.

#### Configuration

There are two ways to configure Tasking Manager. You can set some environment variables on your shell or you can define the configuration in the `tasking-manager.env` file on the repository root directory. To use that last option, follow the below instructions:
There are two ways to configure Tasking Manager. You can set some
environment variables on your shell or you can define the
configuration in the `tasking-manager.env` file on the repository root
directory. To use that last option, follow the below instructions:

* Copy the example configuration file to start your own configuration: `cp example.env tasking-manager.env`.
* Copy the example configuration file to start your own configuration:
`cp example.env tasking-manager.env`.
* Adjust the `tasking-manager.env` configuration file to fit your configuration.
* Make sure that the following variables are set correctly in the `tasking-manager.env` configuration file:
* Make sure that the following variables are set correctly in the
`tasking-manager.env` configuration file:
- `TM_APP_BASE_URL`=web-server-endpoint
- `POSTGRES_DB`=tasking-manager-database-name
- `POSTGRES_USER`=database-user-name
@@ -113,7 +122,8 @@ In order to send email correctly, set these variables as well:

#### Tests

The project includes a suite of Unit and Integration tests that you should run after any changes
The project includes a suite of Unit and Integration tests that you
should run after any changes.

```
python3 -m unittest discover tests/backend
@@ -134,7 +144,13 @@ cd frontend && yarn build-locales

#### Create a fresh database

We use [Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/) to create the database from the migrations directory. Check the instructions on how to setup a PostGIS database with [docker](#creating-a-local-postgis-database-with-docker) or on your [local system](#non-docker). Then you can execute the following command to apply the migrations:
We use
[Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/) to
create the database from the migrations directory. Check the
instructions on how to setup a PostGIS database with
[docker](#creating-a-local-postgis-database-with-docker) or on your
[local system](#non-docker). Then you can execute the following
command to apply the migrations:

```
flask db upgrade
@@ -146,23 +162,35 @@ pdm run upgrade

#### Set permissions to create projects

To be able to create projects and have full permissions as an admin user inside TM, login to the TM with your OSM account to populate your user information in the database, then execute the following command on your terminal (with the OS user that is the owner of the database):
To be able to create projects and have full permissions as an admin
user inside TM, login to the TM with your OSM account to populate your
user information in the database, then execute the following command
on your terminal (with the OS user that is the owner of the database):

`psql -d <your_database> -c "UPDATE users set role = 1 where username = '<your_osm_username>'"`

### API

If you plan to only work on the API you only have to build the backend architecture. Install the backend dependencies, and run the server:
If you plan to only work on the API you only have to build the backend
architecture. Install the backend dependencies, and run the server:

`flask run --debug --reload` or `pdm run start`

You can access the API documentation on [http://localhost:5000/api-docs](http://localhost:5000/api-docs), it also allows you to execute requests on your local TM instance. The API docs is also available on our [production](https://tasks.hotosm.org/api-docs) and [staging](https://tasks-stage.hotosm.org/api-docs/) instances.
You can access the API documentation on
[http://localhost:5000/api-docs](http://localhost:5000/api-docs), it
also allows you to execute requests on your local TM instance. The API
docs is also available on our
[production](https://tasks.hotosm.org/api-docs) and
[staging](https://tasks-stage.hotosm.org/api-docs/) instances.

#### API Authentication

In order to authenticate on the API, you need to have an Authorization Token.

1. Run the command line `manage.py` via `flask` with the `gen_token` option and `-u <OSM_User_ID_number>`. The command line can be run in any shell session as long as you are in the tasking-manager directory.
1. Run the command line `manage.py` via `flask` with the `gen_token`
option and `-u <OSM_User_ID_number>`. The command line can be run
in any shell session as long as you are in the tasking-manager
directory.

```
flask gen_token -u 99999999
@@ -174,27 +202,38 @@ This will generate a line that looks like this:
2. In the Swagger UI, where it says
> Token sessionTokenHere==
replace `sessionTokenHere==` with the string of characters between the apostrophes (' ') above so you end up with something that looks like this in that field:
replace `sessionTokenHere==` with the string of characters between the
apostrophes (' ') above so you end up with something that looks like
this in that field:

> Token SWpFaS5EaEoxRlEubHRVC1DSTVJZ2hfalMc0xlalu3KRk5BUGk0
Your user must have logged in to the local testing instance once of course and have the needed permissions for the API call.
Your user must have logged in to the local testing instance once of
course and have the needed permissions for the API call.

You can get your OSM user id number either by finding it in your local testing/dev database `select * from users` or from OSM by viewing the edit history of your user, selecting a changeset from the list, and then at the bottom link `Changeset XML` and it will be in the `uid` field of the XML returned.
You can get your OSM user id number either by finding it in your local
testing/dev database `select * from users` or from OSM by viewing the
edit history of your user, selecting a changeset from the list, and
then at the bottom link `Changeset XML` and it will be in the `uid`
field of the XML returned.

#### API Authentication on remote instance

To get your token on the production or staging Tasking Manager instances, sign in in the browser and then either:

- go to the user profile page, enable _Expert mode_ in the settings, and copy the token from the _API Key_ section.
- inspect a network request and search for the `Authorization` field in the request headers section.
To get your token on the production or staging Tasking Manager
instances, sign in in the browser and then either:

- go to the user profile page, enable _Expert mode_ in the settings,
and copy the token from the _API Key_ section.
- inspect a network request and search for the `Authorization` field
in the request headers section.

# Docker

## Creating a local PostGIS database with Docker

If you're not able to connect to an existing tasking-manager DB, we have a [Dockerfile]() that will allow you to run PostGIS locally as follows.
If you're not able to connect to an existing tasking-manager DB, we
have a [Dockerfile]() that will allow you to run PostGIS locally as
follows.

### Dependencies

@@ -210,13 +249,15 @@ Following must be available locally:
docker build -t tasking-manager-db ./scripts/docker/postgis
`

2. The image should be downloaded and build locally. Once complete you should see it listed, with
2. The image should be downloaded and build locally. Once complete
you should see it listed, with

`
docker images
`

3. You can now run the image (this will run PostGIS in a docker container, with port 5432 mapped to localhost):
3. You can now run the image (this will run PostGIS in a docker
container, with port 5432 mapped to localhost):

`
docker run -d -p 5432:5432 tasking-manager-db
@@ -228,23 +269,29 @@ docker run -d -p 5432:5432 tasking-manager-db
docker ps
`

5. Finally you can set your env variable to point at your containerised DB:
5. Finally you can set your env variable to point at your
containerised DB:

`
export TM_DB=postgresql://hottm:hottm@localhost/tasking-manager
`

6. Refer to the rest of the instructions in the README to setup the DB and run the app
6. Refer to the rest of the instructions in the README to setup the
DB and run the app.

# Non-Docker

## Creating the PostGIS database

It may be the case you would like to set up the database without using Docker for one reason or another. This provides you with a set of commands to create the database and export the database address to allow you to dive into backend development.
It may be the case you would like to set up the database without using
Docker for one reason or another. This provides you with a set of
commands to create the database and export the database address to
allow you to dive into backend development.

### Dependencies

First, ensure that Postgresql and PostGIS are installed and running on your computer.
First, ensure that Postgresql and PostGIS are installed and running on
your computer.

### Create the database user and database

@@ -265,9 +312,12 @@ export TM_DB=postgresql://hottm:hottm@localhost/tasking-manager
`


It is possible to install and run the Tasking Manager using [Docker](https://docker.com) and [Docker Compose](https://docs.docker.com/compose/).
It is possible to install and run the Tasking Manager using
[Docker](https://docker.com) and [Docker
Compose](https://docs.docker.com/compose/).

Clone the Tasking Manager repository and use `docker-compose up` to get a working version of the API running.
Clone the Tasking Manager repository and use `docker-compose up` to
get a working version of the API running.

## Sysadmins guide

File renamed without changes.
48 changes: 48 additions & 0 deletions docs/developers/review-pr.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@

# Review of Pull Requests

All team members are encouraged to regularly review Pull
Requests (PR). Within the team we are open to assign people we feel
are the best for a certain topic to be checked. A best practice is to
have two reviewers, one that looks more on the code and one that has
an overview of behaviour and functionality. Note that all PRs should
be made from a fork of the primary branch.

For many small PRs, they can be reviewed by clicking on the PR number
to the right side of the patch. For larger PRs you need to checkout
the pull request. You can see the branch name on the page for the
PR. Since you should be developing in a fork, you need to clone the
primary repository to see the PR branch. Once your primary sources are
up to date, you can check out the PR branch.

git checkout BRANCHNAME

To see the differences you can use *git diff*.

git diff BRANCHNAME..develop

1 . Check whether Continuous Integration runs without errors

Have a look on the CI results. In case they fail, add a comment to the
PR and ask the person to check on the error. If the CI tests are good,
you are good to go with the next step.

2 . Review code

Check on the code a using this criterias:

* Is the code of a good quality?
* Are there any typos included?
* Is the code commented?
* Are there unit tests related to new functionality?

If there are any issues, add a comment to the PR page on github. A PR
should not be approved until all issues with the PR are resolved.

3 . Merge a PR

* On the github page for the PR, click the *Merge pull request*
button.
* Delete the PR branch

git push origin --delete BRANCHNAME
52 changes: 52 additions & 0 deletions docs/developers/submit-pr.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Submitting a PR

Before submitting a Pull Request(PR) you should test your changes. If
your changes are nopt covered by any existing test cases, it is
strongly recommended to add a test case. If you are submitting a PR
for a bug, please add the github issue for the bug to the branch name
if possible.

It's better to have multiple PRs with a scope limited to the specific
issue being worked on, than one large one covering multiple
issues. Also creating a PR in draft mode and continuing to commit to
it works fine, but does get confusing for the reviwers. A PR in draft
mode for more than a short time runs the risk of being ignored.

## Tests and coverage

The backend has unit tests which can be run manually. These are the
same tests the CI support runs. To run all the tests, do this:

python3 -m unittest discover ./tests

To run a specific test case, you can do it like this:

python -m unittest tests/backend/integration/services/test_license_service.py

Whenever you add a new endpoint in the backend, you should add a test
case for it.

## Check changes

This is a small list of possible scenarios that you should
test. Ideally, you would check all of them regardless if the answer to
the question is 'no' to make sure there are no collateral issues from
a PR. This should be done in your local docker container, and not on a
production server.

* Are changes made to the frontend? Walk through them logged in and
logged out (if possible).
* Are changes made to the API? Check you can poll it at
`http://localhost:5000/api-docs` if you have Tasking Manager running
in a docker container.
* Do changes touch messaging? Try logging in with two separate
accounts in two browsers (e.g. one open with private browsing) and
interacting between users.
* Do changes effect selecting a task to map ? Check out a task for
mapping and unlock it. Check out another task for mapping and mark
it done. Check out a task and unlock it. Check out a task for
validation and mark it validated. Check out a task for validation
and mark it invalidated.
* Do changes touch on task commenting? Comment on a task without
checking it out. Comment on a task while checked out for
mapping. Comment on a task while checked out for validating.
40 changes: 23 additions & 17 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -4,29 +4,35 @@
[![TM Backend on Quay](https://quay.io/repository/hotosm/tasking-manager/status "Tasking Manager Backend Build")](https://quay.io/repository/hotosm/tasking-manager)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=hotosm_tasking-manager&metric=alert_status)](https://sonarcloud.io/dashboard?id=hotosm_tasking-manager)

[<img src="images/screenshot.jpg" />](./screenshot.jpg)

The most popular tool for teams to coordinate mapping on OpenStreetMap. With this web application, an area of interest can be defined and divided up into smaller tasks that can be completed rapidly. It shows which areas need to be mapped and which areas need a review for quality assurance. You can see the tool in action: log into the widely used [HOT Tasking Manager](https://tasks.hotosm.org/) and start mapping.

This is Free and Open Source Software. You are welcome to use the code and set up your own instance. The Tasking Manager has been initially designed and built by and for the [Humanitarian OpenStreetMap Team](https://www.hotosm.org/), and is nowadays used by many communities and organizations.
![<img src="images/screenshot.jpg" />](images/screenshot.jpg)

The most popular tool for teams to coordinate mapping on
OpenStreetMap. With this web application, an area of interest can be
defined and divided up into smaller tasks that can be completed
rapidly. It shows which areas need to be mapped and which areas need a
review for quality assurance. You can see the tool in action: log into
the widely used [HOT Tasking Manager](https://tasks.hotosm.org/) and
start mapping.

This is Free and Open Source Software. You are welcome to use the code
and set up your own instance. The Tasking Manager has been initially
designed and built by and for the [Humanitarian OpenStreetMap
Team](https://www.hotosm.org/), and is nowadays used by many
communities and organizations.

## Get involved!

* Start by reading our [Code of conduct](https://github.com/hotosm/tasking-manager/blob/develop/docs/code_of_conduct.md)
* Get familiar with our [contributor guidelines](https://github.com/hotosm/tasking-manager/blob/develop/docs/contributing.md) explaining the different ways in which you can support this project! We need your help!
* Join the Tasking Manager Collective Meet up - an opportunity to meet other Tasking Manager contributors. The meet ups take place on the second Wednesday of the month at 9:00 or 15:00UTC! Register to receive a calendar invite: https://bit.ly/3s6ntmV or join directly via this link: https://meet.jit.si/TaskingManagerCollectiveMeetUp
* Join a Tasking Manager [working group](working-groups.md)
* Start by reading our [Code of conduct](developers/code_of_conduct.md)
* Get familiar with our [contributor guidelines](developers/contributing.md)
explaining the different ways in which you can support this project!
We need your help!
* Read the monthly update blogs on [OSM Discourse](https://community.openstreetmap.org/c/general/38/all).

## Product Roadmap
We have included below a [high level roadmap/plan](https://github.com/orgs/hotosm/projects/28/) [subject to change] that can be used as an overview.


## Developers

* [Understand the code](./docs/developers/understanding-the-code.md)
* [Setup the TM for development](./docs/developers/development-setup.md)
* [Learn about versions and releases](./docs/developers/versions-and-releases.md)
* Help us and submit [pull requests](https://github.com/hotosm/tasking-manager/pulls)
We have included below a [high level
roadmap/plan](https://github.com/orgs/hotosm/projects/28/) [subject to
change] that can be used as an overview.

## Instances
* [HOT Tasking Manager (production)](https://tasks.hotosm.org)
115 changes: 79 additions & 36 deletions docs/sysadmins/architecture.md
Original file line number Diff line number Diff line change
@@ -1,52 +1,82 @@
# Architecture

![TM Architecture](../assets/tm-architecture.svg)
![TM Architecture](../images/tm-architecture.svg)

Reference for the [Cloudformation script](../scripts/aws/cloudformation/tasking-manager.template.js):
Reference for the [Cloudformation script](https://github.com/hotosm/tasking-manager/blob/develop/scripts/aws/cloudformation/tasking-manager.template.js):

**TaskingManagerASG** AutoScalingGroup configures the properties of the Autoscaling Group. There is a condition that determines three levels of autoscaling: development (1 instance only), demo (max 3 instances), and production (min 2 max 6 instances).
**TaskingManagerASG** AutoScalingGroup configures the properties of
the Autoscaling Group. There is a condition that determines three
levels of autoscaling: development (1 instance only), demo (max 3
instances), and production (min 2 max 6 instances).

**TaskingManagerScaleUp** Scaling Policy determines the threshold at which the ASG scales up. We use the CloudWatch metric ALBRequestCountPerTarget to keep the number of requests per instance below a certain level.
**TaskingManagerScaleUp** Scaling Policy determines the threshold at
which the ASG scales up. We use the CloudWatch metric
ALBRequestCountPerTarget to keep the number of requests per instance
below a certain level.

**TaskingManagerLaunchConfiguration** has a number of metadata files and commands which are loaded and run during instantiation of a new server into the ASG. The Tasking Manager environment variables are set in this resource.
**TaskingManagerLaunchConfiguration** has a number of metadata files
and commands which are loaded and run during instantiation of a new
server into the ASG. The Tasking Manager environment variables are set
in this resource.

**TaskingManagerEC2Role** IAM role enables the backend servers to communicate with CodeDeploy, CloudWatch monitoring, Cloudformation, and the RDS Database.
**TaskingManagerEC2Role** IAM role enables the backend servers to
communicate with CodeDeploy, CloudWatch monitoring, Cloudformation,
and the RDS Database.

**TaskingManagerDatabaseDumpAccessRole** is an EC2 IAM Role that is only used if a database dump file is given in the configuration, enabling access to the s3 bucket containing that file.
**TaskingManagerDatabaseDumpAccessRole** is an EC2 IAM Role that is
only used if a database dump file is given in the configuration,
enabling access to the s3 bucket containing that file.

**TaskingManagerEC2InstanceProfile** is a required resource for giving a server programmatic access to AWS services.
**TaskingManagerEC2InstanceProfile** is a required resource for giving
a server programmatic access to AWS services.

**TaskingManagerLoadBalancer** configures the security groups and subnets for the Application Load Balancer AWS resource.
**TaskingManagerLoadBalancer** configures the security groups and
subnets for the Application Load Balancer AWS resource.

**TaskingManagerLoadBalancerRoute53** record set for the load balancer.
**TaskingManagerLoadBalancerRoute53** record set for the load
balancer.

**TaskingManagerTargetGroup** configures health checks for each target in the Load Balancer.
**TaskingManagerTargetGroup** configures health checks for each target
in the Load Balancer.

**TaskingManagerLoadBalancerHTTPSListener** assigns the SSL Certificate, protocol, and port to the HTTPS Listener.
**TaskingManagerLoadBalancerHTTPSListener** assigns the SSL
Certificate, protocol, and port to the HTTPS Listener.

**TaskingManagerLoadBalancerHTTPListener** redirects requests to HTTPS.
**TaskingManagerLoadBalancerHTTPListener** redirects requests to
HTTPS.

**TaskingManagerRDS** configures all the properties of the database RDS.
**TaskingManagerRDS** configures all the properties of the database
RDS.

**TaskingManagerReactBucket** is the bucket where the frontend code is stored and served.
**TaskingManagerReactBucket** is the bucket where the frontend code is
stored and served.

**TaskingManagerReactBucketPolicy** gives read access to the objects stored in the bucket.
**TaskingManagerReactBucketPolicy** gives read access to the objects
stored in the bucket.

**TaskingManagerReactCloudfront** configures the CloudFront Distribution for the static frontend stored on S3.
**TaskingManagerReactCloudfront** configures the CloudFront
Distribution for the static frontend stored on S3.

**TaskingManagerRoute53** is the Route53 Record for the frontend, i.e. `tasks.hotosm.org`
**TaskingManagerRoute53** is the Route53 Record for the frontend,
i.e. `tasks.hotosm.org`

### Parameters

**GitSha** is the commit hash from the HOTOSM Tasking Manager repository to be deployed
**GitSha** is the commit hash from the HOTOSM Tasking Manager
repository to be deployed.

**NetworkEnvironment** has only two options- `staging` and `production`, and determines the security groups used for the EC2s and Load Balancer.
**NetworkEnvironment** has only two options- `staging` and
`production`, and determines the security groups used for the EC2s and
Load Balancer.

**AutoscalingPolicy** can be `development`, `demo`, or `production` and determines the min/max number of instances
**AutoscalingPolicy** can be `development`, `demo`, or `production`
and determines the min/max number of instances.

**DBSnapshot** is an optional parameter. Specify the RDS Snapshot ID to create the database from a snapshot
**DBSnapshot** is an optional parameter. Specify the RDS Snapshot ID
to create the database from a snapshot.

**DatabaseDump** is an optional parameter. Specify the s3 bucket object path to create the database from a plaintext dump file.
**DatabaseDump** is an optional parameter. Specify the s3 bucket
object path to create the database from a plaintext dump file.

**NewRelicLicense**

@@ -58,35 +88,48 @@ Reference for the [Cloudformation script](../scripts/aws/cloudformation/tasking-

**DatabaseEngineVersion** AWS PostgreSQL Engine version

**DatabaseInstanceType** is the AWS database instance tier (eg db.t3.large)
**DatabaseInstanceType** is the AWS database instance tier (eg
db.t3.large)

**DatabaseDiskSize** is the size (in GB) of the RDS instance. Recommended at least 100GB for better IOPS
**DatabaseDiskSize** is the size (in GB) of the RDS
instance. Recommended at least 100GB for better IOPS

**DatabaseParameterGroupName** use the default parameter group if you don't know what this is
**DatabaseParameterGroupName** use the default parameter group if you
don't know what this is.

**DatabaseSnapshotRetentionPeriod** Retention period for automatic (scheduled) snapshots in days
**DatabaseSnapshotRetentionPeriod** Retention period for automatic
(scheduled) snapshots in days.

**ELBSubnets** is a comma-separated string of subnets for your AWS region. Make sure the subnets support the EC2 instance type.
**ELBSubnets** is a comma-separated string of subnets for your AWS
region. Make sure the subnets support the EC2 instance type.

**SSLCertificateIdentifier** the ID for the AWS SSL Certificate

**TaskingManagerLogDirectory** the path on the instance where the logs are stored on the server, e.g. `/var/log/tasking-manager/`
**TaskingManagerLogDirectory** the path on the instance where the logs
are stored on the server, e.g. `/var/log/tasking-manager/`

**TaskingManagerClientId** is a key generated by creating and OSM OAuth Client Application.
**TaskingManagerClientId** is a key generated by creating and OSM
OAuth Client Application.

**TaskingManagerClientSecret** is a secret key generated by creating and OSM OAuth Client Application.
**TaskingManagerClientSecret** is a secret key generated by creating
and OSM OAuth Client Application.

**TaskingManagerRedirectUri** allowed URIs to which the user can be redirected after authorizing the application.
**TaskingManagerRedirectUri** allowed URIs to which the user can be
redirected after authorizing the application.

**TaskingManagerScope** are scope(s) which may be requested by a client.

**TaskingManagerSecret** a random string for the frontend and backend to communicate.
**TaskingManagerSecret** a random string for the frontend and backend
to communicate.

**TaskingManagerAppBaseUrl** the full base url of the site, e.g. `https://tasks.hotosm.org/`
**TaskingManagerAppBaseUrl** the full base url of the site,
e.g. `https://tasks.hotosm.org/`.

**TaskingManagerEmailFromAddress** an email address from which messages will be sent to users.
**TaskingManagerEmailFromAddress** an email address from which
messages will be sent to users.

**TaskingManagerEmailContactAddress** a contact address which will show up in places around the site
**TaskingManagerEmailContactAddress** a contact address which will
show up in places around the site

**TaskingManagerLogLevel** can be either `DEBUG` or `INFO`

File renamed without changes.
80 changes: 80 additions & 0 deletions docs/sysadmins/migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Migrate Tasking Manager between major versions

The migrations are always a source for problems and they are made for
us to run and work. But they are not production ready. Therefore,
please do always backups and run the migration first in a testing
environment, make sure everything works as expected before you move
on!

## Migration from version 3 to version 4

First and optionally, you might want to run the following SQL script
against your database for a cleanup of eventual duplications of
priority areas:

$ `psql -d myDataBase -a -f scripts/database/duplicate-priority-area-cleanup.sql`

Now, migrating from version 3 to version 4 can be done through the
build in alembic migrations by simply running:

$ `flask db upgrade` or `pdm run upgrade`

Depending on the size of your database this might take a good while.

## Migration from version 2 to version 3

Migrating from TM2 consists of two main parts: 1) installing the
lastest Tasking Manager application and setting up its unpopulated
database and 2) migrating the data from the original TM2 database to
the new Tasking Manager database.

### Installation

The method by which you install Tasking Manager on your own computer
will vary, but you should follow the [guide to setup a development
environment](../developers/development-setup.md).

Ensure everything is met to start the migration: For this lunch the
new Tasking Manager, go to the main homepage, and click on
"Contribute" while watching the console. It will say there are
currently no projects, which is expected since you have a skeleton
database, but you should make sure no errors are thrown when the
application tries checking for projects. If the page loads
successfully and no errors occur, then you should be set and ready to
continue.

### Database Migration

With the empty database for new Tasking Manager created, we can now
migrate all the data from the TM2 installation. A [database migration
script is included](https://github.com/hotosm/tasking-manager/blob/develop/scripts/database/migration-from-tm2-postgres.sql)
to assist in this process. The beginning of this file contains important
information regarding the assumptions of your prior database name and
permissions, so please read it. That text will walk you through
backing up your old TM2 database and creating a new temporary database
for your TM2 data--though not required, it is recommended.

The database migration script is available at
https://github.com/hotosm/tasking-manager/blob/develop/scripts/database/migration-from-tm2-postgres.sql.

### After Migration

If you followed the instructions in the migration script, you should
have three databases: the original TM one, the temporary TM one, and
one for the new Tasking Manager ("taskingmanager"). You can rename the
the new database to something more intuitive or meaningful:

psql -U my-user -c "ALTER DATABASE taskingmanager rename to my-tasking-manager;"

You can remove the temporary TM2 database:

# PLEASE ONLY RUN THIS IF YOU HAVE FOLLOWED THE
# INSTRUCTIONS IN THE MIGRATION SCRIPT!
psql -U my-user -c "DROP DATABASE tm2;"

It is up to you when you feel comfortable removing the original TM
database. You may also want to manually `vacuum`.

## Migration from version 1 to version 2

There is no known upgrade path. Please inform us, if you know more.
18 changes: 18 additions & 0 deletions docs/working-groups.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# HOT Tasking Manager Monthly Meet Up

HOT runs monthly [Tech and Innovation Working Group Meetings](https://wiki.openstreetmap.org/wiki/Humanitarian_OSM_Team/Working_groups/TechandInnovation) that anyone is welcome to join. They are open for technical and non-technical people who are interested in open source software and geospatial tech. There is a sub-group focused specifically on the HOT Tasking Manager called "HOT Tasking Manager Meet Ups". We hope to see you there!

## Purpose
The purpose of the meet up is to connect with other Tasking Manager enthusiasts, share ideas on how best to collaborate in prioritising, testing and proposing changes in improving the Tasking Manager!


## How to join:
* Join the [HOT slack chat](http://slack.hotosm.org/) and find us in the `#tasking-manager` channel.
* Register using this [form](https://docs.google.com/forms/d/e/1FAIpQLSd2p6cot6l22xthG-4ffOx6SQ_CALWlwc2mN5vQbWPQGAs7Uw/viewform)

## When
Third Wednesdays of each month, 12:00 o'clock UTC (see the [working group calendar](https://calendar.google.com/calendar/embed?src=hotosm.org_848e89aaiab04ag94d23rqn558@group.calendar.google.com) for next meeting).

## Rolling agenda meeting notes

Take a look at the [agenda and notes](https://docs.google.com/document/d/1SW7Klq49pD35k-gQIQT3UhhgVxF4yr6OfNIg1hXFeQA/edit#heading=h.lmgnh7kh0560) from each meeting.
4 changes: 4 additions & 0 deletions frontend/src/components/taskSelection/taskList.js
Original file line number Diff line number Diff line change
@@ -16,6 +16,7 @@ import { LockIcon, ListIcon, ZoomPlusIcon, CloseIcon, InternalLinkIcon } from '.
import { PaginatorLine, howManyPages } from '../paginator';
import { Dropdown } from '../dropdown';
import { TextField } from '../formInputs';
import useCloseOnDocumentClick from '../../hooks/UseCloseOnDocumentClick';

export function TaskStatus({ status, lockHolder }: Object) {
const isReadyOrLockedForMapping = ['READY', 'LOCKED_FOR_MAPPING'].includes(status);
@@ -63,6 +64,8 @@ export function TaskItem({
const location = useLocation();
const { value, unit } = selectUnit(new Date(data.actionDate));

const closeOnDocumentClick = useCloseOnDocumentClick();

const handleCopyToClipboard = () =>
navigator.clipboard
.writeText(`${window.location.origin}${location.pathname}?search=${data.taskId}`)
@@ -117,6 +120,7 @@ export function TaskItem({
<ListIcon width="18px" height="18px" className="pointer hover-blue-grey" />
</div>
}
closeOnDocumentClick={closeOnDocumentClick}
>
{(close) => (
<TaskActivityDetail
50 changes: 50 additions & 0 deletions frontend/src/hooks/UseCloseOnDocumentClick.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
// https://github.com/yjose/reactjs-popup/issues/174
import { useEffect, useState } from 'react';

/**
* This hook is a workaround for an issue in reactjs-popup
*
* What this hook does is:
*
* - on mouse down inside the popup, set closeOnDocumentClick to false
* - on mouse up, set closeOnDocumentClick to true
*
* Usage:
*
* const closeOnDocumentClick = useCloseOnDocumentClick()
*
* return (
* <Popup ... closeOnDocumentClick={closeOnDocumentClick} >
* ...
* </Popup>
* )
*/
export default function useCloseOnDocumentClick() {
const [closeOnDocumentClick, setCloseOnDocumentClick] = useState(true);

useEffect(() => {
function insidePopupContents(target: any): boolean {
return target.querySelector('.popup-content') == null;
}

function handleMouseDown(event: MouseEvent) {
if (insidePopupContents(event.target)) {
setCloseOnDocumentClick(false);
}
}

function handleMouseUp() {
setTimeout(() => setCloseOnDocumentClick(true));
}

window.document.addEventListener('mousedown', handleMouseDown);
window.document.addEventListener('mouseup', handleMouseUp);

return () => {
window.document.removeEventListener('mousedown', handleMouseDown);
window.document.removeEventListener('mouseup', handleMouseUp);
};
}, [setCloseOnDocumentClick]);

return closeOnDocumentClick;
}
21 changes: 15 additions & 6 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -67,17 +67,26 @@ nav:
- Home: index.md
- About: about.md
- For Developers:
# - Understanding the Code: developers/understanding-the-code.md
- Contributing: developers/contributing.md
- Code Of Conduct: developers/code_of_conduct.md
- Contributing Guidelines: developers/contributing-guidelines.md
- Development Setup: developers/development-setup.md
- Reviewing PRs: developers/review-pr.md
- Submitting a PR: developers/submit-pr.md
- Translations: developers/translations.md
- Versions and Releases: developers/versions-and-releases.md
- Error Codes: developers/error_code.md
- Deep Tech Dives:
- Data Flow Diagrams: dataflow.md
- Database Schema: developers/tmschema.md
- Class Hierarchy: apidocs/html/index.html
- For Sysadmins:
# - Monitoring and Logging: sysadmins/monitoring-logging.md
# - Networking: sysadmins/networking-connectivity.md
- Deployment: sysadmins/deployment.md
- CI: sysadmins/ci-cd.md
- Architecture: sysadmins/architecture.md
# - Security and Reliability: sysadmins/security-reliability-processes.md
- Class Hierarchy: apidocs/html/index.html
- Migration: sysadmins/migration.md
- Deployment: sysadmins/deployment.md
- Customize: sysadmins/customize.md
- CI: sysadmins/ci-cd.md
- Working Groups: working-groups.md
- License: LICENSE.md
# - Changelog: CHANGELOG.md