From 92fe80c2b4d50b7674d76209c38d809f5cebd391 Mon Sep 17 00:00:00 2001 From: spwoodcock Date: Sat, 13 Jan 2024 02:38:58 +0000 Subject: [PATCH] docs: fix linting errors for all markdown docs --- CODE_OF_CONDUCT.md | 135 ++++++++--- CONTRIBUTING.md | 54 +++-- README.md | 2 +- docs/About.md | 55 +++-- docs/FAQ.md | 52 ++-- docs/User-Manual-For-Project-Managers.md | 187 ++++++++------ docs/dev/Frontend.md | 13 +- docs/dev/Setup.md | 297 +++++++++++++++-------- 8 files changed, 525 insertions(+), 270 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 6f18f60fde..7da9c5dabe 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,14 +1,25 @@ # ๐Ÿ“œ Code of conduct -(The latest version can be found at ) +(The latest version can be found at [https://www.hotosm.org/code-of-conduct][1] -Welcome to Humanitarian OpenStreetMap Team. HOT is committed to providing a welcoming and safe environment for people of all races, gender identities, gender expressions, sexual orientations, physical abilities, physical appearances, socio-economic backgrounds, nationalities, ages, religions, and beliefs. +Welcome to Humanitarian OpenStreetMap Team. HOT is committed to providing a +welcoming and safe environment for people of all races, gender identities, +gender expressions, sexual orientations, physical abilities, physical +appearances, socio-economic backgrounds, nationalities, ages, religions, and +beliefs. The HOT community principles are: -- **Be friendly and patient.** Be generous and kind in both giving and accepting critique. Critique is a natural and important part of our culture. Good critiques are kind, respectful, clear, and constructive, focused on goals and requirements rather than personal preferences. You are expected to give and receive criticism with grace. Be considerate in speech and actions, and actively seek to acknowledge and respect the boundaries of fellow attendees. +- **Be friendly and patient.** Be generous and kind in both giving and accepting + critique. Critique is a natural and important part of our culture. Good + critiques are kind, respectful, clear, and constructive, focused on goals and + requirements rather than personal preferences. You are expected to give and + receive criticism with grace. Be considerate in speech and actions, and + actively seek to acknowledge and respect the boundaries of fellow attendees. -- **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. Some examples of behavior that contributes to creating a positive environment include: +- **Be welcoming.** We strive to be a community that welcomes and supports + people of all backgrounds and identities. Some examples of behavior that + contributes to creating a positive environment include: - Using welcoming and inclusive language. @@ -20,11 +31,24 @@ The HOT community principles are: - Placing collective interest before your own interest. -- **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language. - -- **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. Itโ€™s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the HOT community should be respectful when dealing with other members as well as with people outside the HOT community. - -- **Be careful in your word choice.** We are a global community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to: +- **Be considerate.** Your work will be used by other people, and you in turn + will depend on the work of others. Any decision you take will affect users and + colleagues, and you should take those consequences into account when making + decisions. Remember that we're a world-wide community, so you might not be + communicating in someone else's primary language. + +- **Be respectful.** Not all of us will agree all the time, but disagreement is + no excuse for poor behavior and poor manners. We might all experience some + frustration now and then, but we cannot allow that frustration to turn into a + personal attack. Itโ€™s important to remember that a community where people feel + uncomfortable or threatened is not a productive one. Members of the HOT + community should be respectful when dealing with other members as well as with + people outside the HOT community. + +- **Be careful in your word choice.** We are a global community of + professionals, and we conduct ourselves professionally. Be kind to others. Do + not insult or put down other participants. Harassment and other exclusionary + behavior aren't acceptable. This includes, but is not limited to: - Violent threats or language directed against another person. @@ -32,7 +56,8 @@ The HOT community principles are: - Posting sexually explicit or violent material. - - Posting (or threatening to post) other people's personally identifying information ("doxing"). + - Posting (or threatening to post) other people's personally identifying + information ("doxing"). - Personal insults, especially those using racist or sexist terms. @@ -40,44 +65,94 @@ The HOT community principles are: - Advocating for, or encouraging, any of the above behavior. - - Repeated harassment of others. In general, if someone asks you to stop, then stop. - -- **Assume all communications are positive.** Always remain polite, and assume good faith. It is surprisingly easy to misunderstand each other, be it online or in person, particularly in such a culturally diverse setting as ours. Misunderstandings are particularly easy to arise when we are in a rush, or otherwise distracted. Please ask clarifying questions before assuming that a communication was inappropriate. - -- **When we disagree, try to understand why.** Disagreements, both social and technical, happen easily and often. It is important that we resolve such disagreements and differing views constructively. At times it can be hard to appreciate a viewpoint that contradicts your own perceptions. Instead of pushing back, try to understand where the other person is coming from, and donโ€™t be afraid to ask questions. You can be most helpful if your own replies serve to clarify, rather than to escalate an issue. Also donโ€™t forget that it can be easy to make mistakes, and allow for the possibility that the mistake may have been yours. When this happens it is better to resolve the issue together, and to learn from the experience together, than to place blame. - -Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html). + - Repeated harassment of others. In general, if someone asks you to stop, then + stop. + +- **Assume all communications are positive.** Always remain polite, and assume + good faith. It is surprisingly easy to misunderstand each other, be it online + or in person, particularly in such a culturally diverse setting as ours. + Misunderstandings are particularly easy to arise when we are in a rush, or + otherwise distracted. Please ask clarifying questions before assuming that a + communication was inappropriate. + +- **When we disagree, try to understand why.** Disagreements, both social and + technical, happen easily and often. It is important that we resolve such + disagreements and differing views constructively. At times it can be hard to + appreciate a viewpoint that contradicts your own perceptions. Instead of pushing + back, try to understand where the other person is coming from, and donโ€™t be + afraid to ask questions. You can be most helpful if your own replies serve to + clarify, rather than to escalate an issue. Also donโ€™t forget that it can be + easy to make mistakes, and allow for the possibility that the mistake may have + been yours. When this happens it is better to resolve the issue together, and + to learn from the experience together, than to place blame. + +Original text courtesy of the [Speak Up! project][1]. Further sources: -- [Ada Initiative: HOWTO design a code of conduct for your community](https://adainitiative.org/2014/02/18/howto-design-a-code-of-conduct-for-your-community/) +- [Ada Initiative: HOWTO design a code of conduct for your community][3] -- [Algorithm Club Code of Conduct](https://github.com/drtortoise/critical-algorithm-studies/blob/master/code-of-conduct.md) +- [Algorithm Club Code of Conduct][4] -- [American Red Cross GIS Team Code of Conduct](https://github.com/AmericanRedCross/team-code-of-conduct) +- [American Red Cross GIS Team Code of Conduct][5] -- [Contributor Covenant โ€“ A Code of Conduct for Open Source Projects](http://contributor-covenant.org/) +- [Contributor Covenant โ€“ A Code of Conduct for Open Source Projects][6] -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) +- [Django Code of Conduct][7] -- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) +- [Mozilla Community Participation Guidelines][8] -- [Vox Media Code of Conduct](http://code-of-conduct.voxmedia.com/) +- [Vox Media Code of Conduct][9] ## Complaint Handling Process -As a first measure, it is preferable to work out issues directly with the people involved, or to work with other Community Members who can help you resolve the issue. This may take several forms: +As a first measure, it is preferable to work out issues directly with the people +involved, or to work with other Community Members who can help you resolve the +issue. This may take several forms: -- Talk with one another. Assume that communications are positive and that people are treating each other with respect. Cues about emotions are often lacking from digital communications. Many of our modes of digital communication tend towards brevity, which can be easier to interpret incorrectly as being negative. +- Talk with one another. Assume that communications are positive and that people + are treating each other with respect. Cues about emotions are often lacking + from digital communications. Many of our modes of digital communication tend + towards brevity, which can be easier to interpret incorrectly as being negative. -- Contact a representative of the [Community Working Group](https://www.hotosm.org/community/working-groups/), which exists to support the HOT Community. Representatives are available to discuss any concerns about behaviour within the community, or ideas to promote positive behaviours. You can email them at [community@hotosm.org](mailto:community@hotosm.org). +- Contact a representative of the [Community Working Group][10], which exists to + support the HOT Community. Representatives are available to discuss any + concerns about behaviour within the community, or ideas to promote positive + behaviours. You can email them at + [community@hotosm.org](mailto:community@hotosm.org). -- Contact a representative of the [Governance Working Group](https://www.hotosm.org/community/working-groups/), which drafted these recommendations and the CoC. Representatives are available to provide advice on particular scenarios, as well as on the processes around the CoC. +- Contact a representative of the [Governance Working Group][11], which drafted + these recommendations and the CoC. Representatives are available to provide + advice on particular scenarios, as well as on the processes around the CoC. - Contact the HOT Chair of Voting Members. -- Contact a [HOT Board Member](https://www.hotosm.org/board). Board members are well versed in the community and its management. They can offer advice on your particular situation, and know the resources of the organization that may be available to you. +- Contact a [HOT Board Member][12]. Board members are well versed in the + community and its management. They can offer advice on your particular + situation, and know the resources of the organization that may be available to + you. - Contact the HOT Community Partnerships Manager. -When these informal processes fail, or when a situation warrants an immediate response by HOT, you can evoke the **HOT Policy and Code of Conduct Complaint Handling Process**. This process was adopted by HOT Voting Members in 2016 to provide a more formal means of enforcement for our community standards. You start it by emailing [complaints@hotosm.org](mailto:compaints@hotosm.org) with a description of your complaint, your name, and the name of the offending party. All complaints will be considered confidential. The full process is described [here](https://docs.google.com/document/d/1xb-SPADtSbgwl6mAgglHMPHpknt-E7lKRoIcSbW431A/edit) . +When these informal processes fail, or when a situation warrants an immediate +response by HOT, you can evoke the +**HOT Policy and Code of Conduct Complaint Handling Process**. +This process was adopted by HOT Voting Members in 2016 to provide a more formal +means of enforcement for our community standards. You start it by emailing +[complaints@hotosm.org](mailto:compaints@hotosm.org) with a description of +your complaint, your name, and the name of the offending party. +All complaints will be considered confidential. +The full process is described [here][13] . + +[1]: https://www.hotosm.org/code-of-conduct +[3]: https://adainitiative.org/2014/02/18/howto-design-a-code-of-conduct-for-your-community/ +[4]: https://github.com/drtortoise/critical-algorithm-studies/blob/master/code-of-conduct.md +[5]: https://github.com/AmericanRedCross/team-code-of-conduct +[6]: http://contributor-covenant.org/ +[7]: https://www.djangoproject.com/conduct/ +[8]: https://www.mozilla.org/en-US/about/governance/policies/participation/ +[9]: http://code-of-conduct.voxmedia.com/ +[10]: https://www.hotosm.org/community/working-groups/ +[11]: https://www.hotosm.org/community/working-groups/ +[12]: https://www.hotosm.org/board +[13]: https://docs.google.com/document/d/1xb-SPADtSbgwl6mAgglHMPHpknt-E7lKRoIcSbW431A/edit diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 322f93b478..d3bd33f42b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,33 @@ -## ๐Ÿค— Welcome +# ๐Ÿค— Welcome -:+1::tada: First off, We are really glad you're reading this, because we need volunteer developers to help improve the Field Mapping Tasking Manager (FMTM)! :tada::+1: +:+1::tada: First off, We are really glad you're reading this, because we need +volunteer developers to help improve the Field Mapping Tasking Manager (FMTM)! +:tada::+1: -We welcome and encourage contributors of all skill levels, and we are committed to making sure your participation is inclusive, enjoyable, and rewarding. If you have never contributed to an open source project before, we are a good place to start, and we will make sure you are supported every step of the way. If you have **any** questions, please ask! +We welcome and encourage contributors of all skill levels, and we are committed +to making sure your participation is inclusive, enjoyable, and rewarding. If +you have never contributed to an open source project before, we are a good +place to start, and we will make sure you are supported every step of the way. +If you have **any** questions, please ask! -You can see an overview of the project and the process we have gone through in developing FMTM so far in these [slides](https://docs.google.com/presentation/d/1UrBG1X4MXwVd8Ps498FDlAYvesIailjjPPJfR_B4SUs/edit#slide=id.g15c1f409958_0_0) . +You can see an overview of the project and the process we have gone through in +developing FMTM so far in these +[slides]( +1UrBG1X4MXwVd8Ps498FDlAYvesIailjjPPJfR_B4SUs/edit#slide=id.g15c1f409958_0_0) -Furthermore, there are many ways to contribute to the **Field Mapping Tasking Manager (FMTM)**, which includes: +Furthermore, there are many ways to contribute to the +**Field Mapping Tasking Manager (FMTM)**, which includes: ## Testing -Right now, we are in the process of building the prototype. We warmly welcome your input in testing and sharing your feedback. If you are also interested in coordinating a field testing session, please reach out! +Right now, we are in the process of building the prototype. We warmly welcome +your input in testing and sharing your feedback. If you are also interested in +coordinating a field testing session, please reach out! ## Code contributions -Create pull requests (PRs) for changes that you think are needed. We would really appreciate your help! +Create pull requests (PRs) for changes that you think are needed. We would +really appreciate your help! Skills with the following would be beneficial: @@ -25,20 +38,29 @@ Skills with the following would be beneficial: - Docker - CI/CD workflows -Our latest task board can be found [here](https://github.com/orgs/hotosm/projects/22). +Our latest task board can be found +[here](https://github.com/orgs/hotosm/projects/22). ## Report bugs and suggest improvements -The [issue queue](https://github.com/hotosm/fmtm/issues) is the best way to get started. There are issue templates for BUGs and FEATURES that you can use, you could also create your own. Once you have submitted an issue, it will be assigned one label from the following [label categories](https://github.com/hotosm/fmtm/labels). If you are wondering where to start, you can filter by the **good first issue label**. +The [issue queue](https://github.com/hotosm/fmtm/issues) is the best way to get +started. There are issue templates for BUGs and FEATURES that you can use, you +could also create your own. Once you have submitted an issue, it will be +assigned one label from the following +[label categories](<). +If you are wondering where to start, you can filter by the +**good first issue label**. ## :handshake: Thank you -Thank you very much in advance for your contributions!! Please ensure you refer to our **Code of Conduct**. -If you've read the guidelines, but are still not sure how to contribute on Github, please reach out to us via our Slack **#geospatial-tech-and-innovation**. +Thank you very much in advance for your contributions!! Please ensure you refer +to our **Code of Conduct**. +If you've read the guidelines, but are still not sure how to contribute on +Github, please reach out to us via our Slack **#geospatial-tech-and-innovation**. -# Code Contribution guidelines +## Code Contribution guidelines -## Workflow +### Workflow We operate the "Fork & Pull" model explained at [About Pull Requests](https://help.github.com/articles/about-pull-requests/) @@ -58,7 +80,7 @@ complications with other developers. The old free software joke is "patches are better than bug reports" is how we contribute to the community of people involved with this project. -# If you are reporting a problem +### If you are reporting a problem - Describe exactly what you were trying to achieve, what you did, what you expected to happen and what did happen instead. Include relevant information @@ -70,7 +92,7 @@ community of people involved with this project. keeps issues small and manageable and makes it much easier to follow through and make sure each problem is taken care of. -## Documentation +### Documentation Project documentation should be in [Markdown format](https://www.markdownguide.org/), and in a _docs_ @@ -78,7 +100,7 @@ subdirectory. While it is possible to use HTML in Markdown documents for tables and images, it is prefered to use the Markdown style as it's much easier to read. -## Coding Style +### Coding Style Python enforces a certain amount of style due to indent levels. Unlike C/C++, we don't have to worry about curly braces. It is prefered that diff --git a/README.md b/README.md index 7fc44c8c9e..f33fe49768 100644 --- a/README.md +++ b/README.md @@ -248,7 +248,7 @@ Its functions include: This is pretty straightforward using [OpenPyXL](https://openpyxl.readthedocs.io/en/stable/), though we have to be careful to keep the location within the spreadsheet of these two items consistent. - - GeoJSON feature collections for each form (the buildings/amenities or whatever) + - GeoJSON feature collections for each form (the buildings/amenities etc) - An App User for each form, which in turn corresponds to a single task. When the ODK Collect app on a user's phone is configured to function as that App User, they have access to diff --git a/docs/About.md b/docs/About.md index 83c6dd2f36..d49bd8a3a4 100644 --- a/docs/About.md +++ b/docs/About.md @@ -1,6 +1,6 @@ -## ๐Ÿ“– History +# ๐Ÿ“– History -### How was FMTM born? +## How was FMTM born? It started as Ivan's idea to build FMTM (Ivan Gayton is Senior Humanitarian Advisor at Humanitarian OpenStreetMap Team) which then became a collaborative @@ -10,24 +10,23 @@ volunteers interested in the project. HOT uses ODK heavily, but most of the data never makes it into OSM because all the data processing is manual and slow, so it doesn't get done. - + Ivan Gayton(Senior Humanitarian Advisor at Humanitarian OpenStreetMap Team) heard about what Rob was working on and goes "That's the missing piece I needed!". He'd been wanting to build FMTM for years, but lacked the ability to process the data. -A [webinar](https://www.youtube.com/watch?v=GiLKRZpbtrc&ab_channel=HumanitarianOpenStreetMapTeam) then took place in September 2022 +A [webinar][1] then took place in September 2022 that showcased the high interest from the community and the need for collaborative field mapping that really kicked off the starting point for building the Field Mapping Tasking Manager. It was Ivan who got HOT interested enough to direct some resources to his idea, so FMTM was born. -**\_Want to know about OSM-fieldwork project ?** -Click [here](https://github.com/hotosm/osm-fieldwork/wiki) -
-
-
-
+**Want to know about OSM-fieldwork project?** click [here][2] ## A project to provide tools for Open Mapping campaigns @@ -51,19 +50,19 @@ analytics and reporting features, allowing users to gain insights into mapping campaigns and adjust their strategies accordingly. Background and description of the project and idea are -[here](https://www.hotosm.org/updates/field-mapping-is-the-future-a-tasking-manager-workflow-using-odk/): +[here][3]: please have a look at this blog if you haven't yet! -# How to contribute +## How to contribute The FMTM project is open source and community-driven, welcoming contributions from designers, user testers, and both front-end and back-end developers. If you're interested in getting involved, please see our -[contributor guidelines](https://github.com/hotosm/fmtm/blob/main/CONTRIBUTING.md) +[contributor guidelines][4] for more information. We welcome questions and feedback, so don't hesitate to reach out to us. ๐Ÿ‘๐ŸŽ‰ -# Using OpenDataKit's Select From Map feature +## Using OpenDataKit's Select From Map feature OpenDataKit's Select From Map feature is a useful tool for field mappers to collect data in a well-structured questionnaire format. The tool was @@ -80,21 +79,25 @@ floors, construction material, or any number of useful attributes in a well-structured questionnaire format To prepare the appropriate map files for ODK, we are taking our inspiration from -the [HOT Tasking Manager](https://tasks.hotosm.org/), which allows remote +the [HOT Tasking Manager][5], which allows remote mappers to choose well-defined small "task" areas, ensuring full coverage of the project area and no unintended duplication of tasks. -# Users +## Users There are three main user roles for using ODK's Select From Map feature: campaign managers, field mappers, and validators. -## Campaign managers +### Campaign managers Campaign managers select an Area of Interest (AOI) and organize field mappers to go out and collect data. They need to: - + - Select an AOI polygon by creating a GeoJSON or by tracing a polygon in a Web map @@ -107,7 +110,7 @@ to go out and collect data. They need to: - See the status of tasks (open, "checked out", completed but not validated, requires to rework, validated, etc) in the Web browser on their computer -## Field mappers +### Field mappers Field mappers select (or are allocated) individual tasks within a project AOI and use ODK Collect to gather data in those areas. They need to: @@ -116,7 +119,7 @@ and use ODK Collect to gather data in those areas. They need to: - Choose an area and launch ODK Collect with the form corresponding to their allocated area pre-loaded -## Validators +### Validators Validators review the data collected by field mappers and assess its quality. If the data is good, the validators merge the portion of the data that @@ -132,7 +135,13 @@ that they need to fix it. They need to: - Merge good-quality data into OSM (probably from JOSM). - Mark areas as completed and merged. -# Info for developers +## Info for developers -For this visit the -[Getting Started Page](https://hotosm.github.io/fmtm/dev/Setup/). +For this visit the [Getting Started Page][6] + +[1]: https://www.youtube.com/watch?v=GiLKRZpbtrc&\ab_channel=HumanitarianOpenStreetMapTeam +[2]: https://github.com/hotosm/osm-fieldwork/wiki +[3]: https://www.hotosm.org/updates/field-mapping-is-the-future-a-tasking-manager-workflow-using-odk +[4]: https://github.com/hotosm/fmtm/blob/main/CONTRIBUTING.md +[5]: https://tasks.hotosm.org/ +[6]: https://hotosm.github.io/fmtm/dev/Setup/ diff --git a/docs/FAQ.md b/docs/FAQ.md index a0fd7acd5e..4a33af6e68 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,6 +1,6 @@ -## :question: Frequently Asked Questions :question +# โ“ Frequently Asked Questions โ“ -### For Users +## For Users Q: What is FMTM? @@ -8,7 +8,7 @@ Q: What is FMTM? application that facilitates remote monitoring of field activities for humanitarian organizations. -
+--- **Q:** Do I need to create an account to use the FMTM Web App? @@ -16,7 +16,7 @@ humanitarian organizations. creating an account allows you to contribute to mapping projects and access additional features. -
+--- **Q:** How do I browse and select mapping projects on the FMTM Web App? @@ -25,7 +25,7 @@ clicking on the "Projects" tab and selecting a project of interest. You can view project details, tasks, and mapping data on the project page. -
+--- **Q:** How do I contribute to a mapping project on the FMTM Web App? @@ -34,7 +34,7 @@ create an account, select a project of interest, and choose a task to work on. You can then use the mapping tools provided to complete the task. -
+--- **Q:** Can I work on multiple mapping tasks at the same time on the FMTM Web App? @@ -42,7 +42,7 @@ task. FMTM Web App, as long as you can commit the necessary time and effort to each task. -
+--- **Q:** How do I know if my mapping work on the FMTM Web App is accurate? @@ -50,7 +50,7 @@ to each task. review and validate the mapping work. This helps to ensure the accuracy of the mapping data. -
+--- **Q:** Can I provide feedback on a mapping project on the FMTM Web App? @@ -58,7 +58,7 @@ accuracy of the mapping data. App by leaving a comment on the project page or contacting the project manager. -
+--- **Q:** How do I download mapping data from a project on the FMTM Web App? @@ -66,7 +66,7 @@ manager. can select the project of interest and click on the "Export" button on the project page. -
+--- **Q:** Can I use the mapping data from the FMTM Web App for my own research or projects? @@ -75,9 +75,9 @@ available for use, but it is important to check the specific project requirements and licenses before using the data for your own research or projects. -
+--- -### For Contributors +## For Contributors **Q:** What is the Field Mapping Tasking Manager (FMTM)? @@ -85,14 +85,14 @@ or projects. allows contributors to participate in mapping projects related to humanitarian and development work. -
+--- **Q:** How can I become a contributor to the FMTM? **A:** To become a contributor to the FMTM, you can create an account on the platform and join a mapping project. -
+--- **Q:** Who can contribute to FMTM? @@ -100,7 +100,7 @@ the platform and join a mapping project. contributions from developers, designers, and other contributors are always welcome. -
+--- **Q:** What kind of contributions can I make to FMTM? @@ -126,7 +126,7 @@ Translation: If you are fluent in a language other than English, you can contribute by translating the application or its documentation into your language. -
+--- **Q:** What technologies are used in FMTM? @@ -134,7 +134,7 @@ into your language. Postgres, Redis, Celery, and Vue.js. The codebase is written in Python, HTML, CSS, and JavaScript. -
+--- **Q:** How do I set up FMTM locally? @@ -142,7 +142,7 @@ Python, HTML, CSS, and JavaScript. and Node.js installed on your system. You can follow the instructions in the README file of the FMTM repository to set up the project. -
+--- **Q:** How can I report a bug or suggest a new feature for FMTM? @@ -151,7 +151,7 @@ the FMTM repository on GitHub. Be sure to provide as much detail as possible, including steps to reproduce the bug, screenshots, or mockups for new features. -
+--- **Q:** How can I contribute to FMTM if I'm new to open source or web development? @@ -163,7 +163,7 @@ issues labeled as "good first issue." Additionally, you can join the FMTM community on Slack to connect with other contributors and get help with your contributions. -
+--- **Q:** What are the benefits of contributing to the FMTM? @@ -171,7 +171,7 @@ help with your contributions. humanitarian and development work, while also developing your mapping skills and knowledge. -
+--- **Q:** Do I need to have prior mapping experience to contribute to the FMTM? @@ -179,7 +179,7 @@ skills and knowledge. FMTM. The platform provides training and resources to help new contributors get started. -
+--- **Q:** How do I know which mapping project to join? @@ -188,7 +188,7 @@ location, the organization sponsoring the project, and the mapping goals. Review the project information and choose a project that interests you. -
+--- **Q:** Can I work on multiple mapping projects at the same time? @@ -196,7 +196,7 @@ interests you. time. However, it is important to ensure that you can commit the necessary time and effort to each project. -
+--- **Q:** How do I get feedback on my mapping work? @@ -204,7 +204,7 @@ necessary time and effort to each project. review and provide feedback on mapping work. You can also contact project managers or experienced contributors for additional feedback. -
+--- **Q:** How can I improve my mapping skills? @@ -212,7 +212,7 @@ project managers or experienced contributors for additional feedback. mapping skills. You can also join mapping communities and forums to connect with other contributors and learn from their experiences. -
+--- **Q:** Can I use the mapping data for my own research or projects? diff --git a/docs/User-Manual-For-Project-Managers.md b/docs/User-Manual-For-Project-Managers.md index b2b559d3d3..aa0de1566d 100644 --- a/docs/User-Manual-For-Project-Managers.md +++ b/docs/User-Manual-For-Project-Managers.md @@ -1,7 +1,7 @@ # User Manual for FMTM -
-This manual is a step by step guide for the project managers on how to get started with the Field Mapping Tasking Manager. +This manual is a step by step guide for the project managers on how to get +started with the Field Mapping Tasking Manager. - [Introduction](#introduction) - [An Overview Of FMTM In Relations With HOT, OSM and ODK.](#an-overview-of-fmtm-in-relations-with-hot-osm-and-odk) @@ -78,8 +78,12 @@ and improve the effectiveness of humanitarian efforts. ## Prerequisites - Stable Internet connection -- Knowledge on field mapping . If you are new to mapping we suggest you to read [this](https://tasks.hotosm.org/learn/map) . -- Account on ODK Central Server. [Here are the instructions for setting up an ODK Central server on Digital Ocean](https://docs.getodk.org/central-install-digital-ocean/) (it's very similar on AWS or whatever) +- Knowledge on field mapping . If you are new to mapping we suggest you to read + [this](https://tasks.hotosm.org/learn/map) . +- Account on ODK Central Server. + [Here](https://docs.getodk.org/central-install-digital-ocean/) + are the instructions for setting up an ODK Central server on Digital Ocean + (it's very similar on AWS etc) ## Video Tutorial @@ -102,107 +106,154 @@ and improve the effectiveness of humanitarian efforts. ## Steps to create a project in FMTM 1. Go to [fmtm](https://fmtm.hotosm.org/) . -2. In the header, you'll find three tabs: Explore Projects, Manage Organization, and Manage Categories. +2. In the header, you'll find three tabs: Explore Projects, Manage Organization, + and Manage Categories. - ![WhatsApp Image 2023-06-23 at 1 23 07 PM](https://github.com/hotosm/fmtm/assets/97789856/c0d272f0-c69c-483f-9e9d-83dd75b9e748) + ![fmtm dashboard](https://github.com/hotosm/fmtm/assets/97789856/c0d272f0-c69c-483f-9e9d-83dd75b9e748) -3. Start by exploring the projects listed by different nations and world communities for field mapping exercises. -4. Use the filters or search option to narrow down the project cards based on your preferences. - ![WhatsApp Image 2023-06-23 at 1 21 05 PM](https://github.com/hotosm/fmtm/assets/97789856/a5d61628-70e6-426c-a860-b9c7968b4dea) -5. If you are not logged into the system, the "Create new project" button will be disabled. -6. If you are new then on the top right cornor click on Sign up and create an account . Else , Sign in to your existing account . -7. Once signed in, the "Create new project" button will be enabled. Click on it. -8. The process of creating a new project involves four steps: Project Details, Uploading the Area, Defining the Task, and Selecting the Form. -9. Start by filling in the project details, including the organization name, project name, description, and other relevant information. - -![2](https://github.com/hotosm/fmtm/assets/97789856/97c38c80-aa0e-4fe2-b8a5-f4ee43a9a63a) - -10. If your organization's name is not listed, you can add it through the "Manage Organization" tab. -11. Provide the necessary credentials for the ODK (Open Data Kit) central setup, including URL, username, and password. -12. Proceed to the next step, which is uploading the area for field mapping. Choose the file option and select the AOI (Area of Interest) file in GEOJSON file format. - Review the displayed map that corresponds to your selected area and click on "Next". +3. Start by exploring the projects listed by different nations and world + communities for field mapping exercises. +4. Use the filters or search option to narrow down the project cards based on + your preferences. -![3](https://github.com/hotosm/fmtm/assets/97789856/680eb831-790a-48f1-8997-c20b5213909d) + ![project filters](https://github.com/hotosm/fmtm/assets/97789856/a5d61628-70e6-426c-a860-b9c7968b4dea) -13. Define the tasks of the project. - ![WhatsApp Image 2023-06-23 at 1 38 18 PM](https://github.com/hotosm/fmtm/assets/97789856/177d8258-900e-447f-906a-28aeb1fd6b03) +5. If you are not logged into the system, the "Create new project" button will + be disabled. +6. If you are new then on the top right cornor click on Sign up and create an + account . Else , Sign in to your existing account . +7. Once signed in, the "Create new project" button will be enabled. Click on it. +8. The process of creating a new project involves four steps: Project Details, + Uploading the Area, Defining the Task, and Selecting the Form. +9. Start by filling in the project details, including the organization name, + project name, description, and other relevant information. -If you choose "Divide on Square," specify the dimensions of the square tasks. -Click on "Next" to proceed. + ![project details 2](https://github.com/hotosm/fmtm/assets/97789856/97c38c80-aa0e-4fe2-b8a5-f4ee43a9a63a) -![WhatsApp Image 2023-06-23 at 1 17 37 PM](https://github.com/hotosm/fmtm/assets/97789856/f53d76b4-e6cc-44a4-8c7c-00082eb72693) +10. If your organization's name is not listed, you can add it through the + "Manage Organization" tab. +11. Provide the necessary credentials for the ODK (Open Data Kit) central setup, + including URL, username, and password. +12. Proceed to the next step, which is uploading the area for field mapping. + Choose the file option and select the AOI (Area of Interest) file in GEOJSON + file format. + Review the displayed map that corresponds to your selected area and click + on "Next". -14. Select Form . Select the form category you want to use for the field mapping, such as "Data Extract" or any other relevant category. - Choose a specific form from the existing categories or upload a custom form if needed. - Click on "Submit" to proceed. + ![project create info](https://github.com/hotosm/fmtm/assets/97789856/680eb831-790a-48f1-8997-c20b5213909d) -![WhatsApp Image 2023-06-23 at 1 37 19 PM](https://github.com/hotosm/fmtm/assets/97789856/f9a4bed7-d1a9-44dd-b2d4-b55f428f9416) +13. Define the tasks of the project. -15. Wait for the system to generate QR codes for each task, which will be used later in the field mapping process. -16. After the QR codes are generated, you can find your project in the project dashboard. + ![project create area](https://github.com/hotosm/fmtm/assets/97789856/177d8258-900e-447f-906a-28aeb1fd6b03) -
+ If you choose "Divide on Square," specify the dimensions of the square tasks. -## Steps to start access your project and Start mapping or a mapping campaign + Click on "Next" to proceed. -1. Go to the Explore projects tab . Click on the project card and proceed to the next step. -2. Select one of the available tasks and start the field mapping exercise. - ![WhatsApp Image 2023-06-23 at 1 26 39 PM](https://github.com/hotosm/fmtm/assets/97789856/162af2e0-dbfa-4787-8037-f03e71417df8) + ![project task split](https://github.com/hotosm/fmtm/assets/97789856/f53d76b4-e6cc-44a4-8c7c-00082eb72693) -3. If a task is already locked by another user, choose a different task that is available for mapping.If a task is already locked by another user, choose a different task that is available for mapping. +14. Select Form . Select the form category you want to use for the field + mapping, such as "Data Extract" or any other relevant category. -- The drop down icon beside **LEGEND** displays a color code. This - color code lets you know the status of each task on the map. + Choose a specific form from the existing categories or upload a custom form + if needed. + Click on "Submit" to proceed. - - **READY** means that task is available to be mapped - - **LOCKED FOR MAPPING** means that task is already being mapped by another volunteer and therefore unavailable for mapping - - **MAPPED** or **READY FOR VALIDATION** means that task has been completely mapped and ready to be validated. - - **LOCKED FOR VALIDATION** means that task has been mapped and being validated. - - **VALIDATED** means that task has successfully been validated and completely mapped with no errors - - **INVALIDATED** or **MORE MAPPING NEEDED** means that task did not pass the validation process and needs more mapping - - **BAD** means that task is not clear and cannot be mapped + ![project creation status](https://github.com/hotosm/fmtm/assets/97789856/f9a4bed7-d1a9-44dd-b2d4-b55f428f9416) -> Note: 'task' refers to each section of the map enclosed in the dotted -> lines and each task has a corresponding number tag. +15. Wait for the system to generate QR codes for each task, which will be used + later in the field mapping process. +16. After the QR codes are generated, you can find your project in the project + dashboard. -![WhatsApp Image 2023-06-23 at 1 29 10 PM](https://github.com/hotosm/fmtm/assets/97789856/2c0397b0-1829-420a-982e-3d971b514f2c) +## Steps to start access your project and Start mapping or a mapping campaign -- To begin mapping, click on a task closest to you that has the color - code associated with **READY** and change it's status from **READY** - to **LOCKED FOR MAPPING**. Remember to take note of the number tag. -- Scroll to the bottom of the page. The **ACTIVITIES** tab shows the - tasks either **LOCKED FOR MAPPING**, **BAD** or **LOCKED FOR - VALIDATION**. You can search for tasks with the status mentioned - using the number tag associated with each task. +1. Go to the Explore projects tab . Click on the project card and proceed to the + next step. +2. Select one of the available tasks and start the field mapping exercise. -4. Use the QR code to start mapping the selected task using the ODK Collect app on your mobile phone. + ![select task](https://github.com/hotosm/fmtm/assets/97789856/162af2e0-dbfa-4787-8037-f03e71417df8) + +3. If a task is already locked by another user, choose a different task that is + available for mapping.If a task is already locked by another user, choose a + different task that is available for mapping. + + - The drop down icon beside **LEGEND** displays a color code. This + color code lets you know the status of each task on the map. + + - **READY** means that task is available to be mapped + - **LOCKED FOR MAPPING** means that task is already being mapped by another + volunteer and therefore unavailable for mapping + - **MAPPED** or **READY FOR VALIDATION** means that task has been completely + mapped and ready to be validated. + - **LOCKED FOR VALIDATION** means that task has been mapped and being + validated. + - **VALIDATED** means that task has successfully been validated and completely + mapped with no errors + - **INVALIDATED** or **MORE MAPPING NEEDED** means that task did not pass the + validation process and needs more mapping + - **BAD** means that task is not clear and cannot be mapped + + > Note: 'task' refers to each section of the map enclosed in the dotted + > lines and each task has a corresponding number tag. + + ![map legend](https://github.com/hotosm/fmtm/assets/97789856/2c0397b0-1829-420a-982e-3d971b514f2c) + + - To begin mapping, click on a task closest to you that has the color + code associated with **READY** and change it's status from **READY** + to **LOCKED FOR MAPPING**. Remember to take note of the number tag. + - Scroll to the bottom of the page. The **ACTIVITIES** tab shows the + tasks either **LOCKED FOR MAPPING**, **BAD** or **LOCKED FOR + VALIDATION**. You can search for tasks with the status mentioned + using the number tag associated with each task. + +4. Use the QR code to start mapping the selected task using the ODK Collect app + on your mobile phone. 5. Install and open the ODK Collect app on your phone. 6. Set up the project details by scanning the QR code provided. -7. Once the project is set up in the app, start a new form based on the selected form from the project setup. +7. Once the project is set up in the app, start a new form based on the selected + form from the project setup. 8. Fill in the questionnaires and collect data for the field mapping exercise. 9. Save and send the completed form to the server. -10. After completing the assigned task, go back to the project platform on FMTM and mark it as fully mapped. +10. After completing the assigned task, go back to the project platform on FMTM + and mark it as fully mapped. ## Help and Support -If you encounter any issues or need assistance while using FMTM, you can access the following resources: +If you encounter any issues or need assistance while using FMTM, you can access +the following resources: - Check the [FAQs](https://hotosm.github.io/fmtm/FAQ) . - Ask your doubts in the [Slack channel: #fmtm-field-pilots](https://hotosm.slack.com/archives/C04PCBFDEGN) ## Thank you -We are excited to have you join our community of passionate mappers and volunteers. FMTM is a powerful platform developed by the Humanitarian OpenStreetMap Team (HOT) to facilitate mapping projects for disaster response, humanitarian efforts, and community development. +We are excited to have you join our community of passionate mappers and +volunteers. FMTM is a powerful platform developed by the Humanitarian +OpenStreetMap Team (HOT) to facilitate mapping projects for disaster response, +humanitarian efforts, and community development. -With FMTM, you have the opportunity to make a real impact by mapping areas that are in need of support. Your contributions help create detailed and up-to-date maps that aid organizations and communities in their efforts to respond to crises, plan infrastructure, and improve the lives of people around the world. +With FMTM, you have the opportunity to make a real impact by mapping areas that +are in need of support. Your contributions help create detailed and up-to-date +maps that aid organizations and communities in their efforts to respond to +crises, plan infrastructure, and improve the lives of people around the world. -Whether you are a seasoned mapper or new to the world of mapping, FMTM provides a user-friendly interface and a range of tools to make your mapping experience smooth and rewarding. You can create tasks, collaborate with other volunteers, and contribute to ongoing projects that align with your interests and expertise. +Whether you are a seasoned mapper or new to the world of mapping, FMTM provides +a user-friendly interface and a range of tools to make your mapping experience +smooth and rewarding. You can create tasks, collaborate with other volunteers, +and contribute to ongoing projects that align with your interests and expertise. -By mapping with FMTM, you are joining a global community of dedicated individuals who share a common goal of using open data to make a positive difference. Together, we can create a more resilient and inclusive world. +By mapping with FMTM, you are joining a global community of dedicated +individuals who share a common goal of using open data to make a positive +difference. Together, we can create a more resilient and inclusive world. -Explore the projects, join tasks, and contribute your skills to help us build accurate and comprehensive maps. Don't hesitate to ask questions, seek guidance, and engage with fellow mappers through our forums and communication channels. +Explore the projects, join tasks, and contribute your skills to help us build +accurate and comprehensive maps. Don't hesitate to ask questions, seek +guidance, and engage with fellow mappers through our forums and communication +channels. -Thank you for being part of FMTM. Your mapping efforts are invaluable, and we appreciate your commitment to making a difference. +Thank you for being part of FMTM. Your mapping efforts are invaluable, and we +appreciate your commitment to making a difference. Happy mapping! diff --git a/docs/dev/Frontend.md b/docs/dev/Frontend.md index a66fc0a0ba..f52c322791 100644 --- a/docs/dev/Frontend.md +++ b/docs/dev/Frontend.md @@ -11,13 +11,17 @@ For details on how to run the API first, please see: ### 1B: Starting the Frontend Containers -1. You will need to [Install Docker](https://docs.docker.com/engine/install/) and ensure that it is running on your local machine. +1. You will need to [Install Docker](https://docs.docker.com/engine/install/) + and ensure that it is running on your local machine. 2. From the command line: navigate to the top level directory of the FMTM project. 3. From the command line run: `docker compose build ui` - This is essential, as the development container for the frontend is different to production. + This is essential, as the development container for the frontend is + different to production. 4. Once everything is built, from the command line run: `docker compose up -d ui` -5. If everything goes well you should now be able to **navigate to the project in your browser:** +5. If everything goes well you should now be able to + **navigate to the project in your browser:** + [http://fmtm.localhost:7050](http://fmtm.localhost:7050) > Note: during development, if you rebuild the frontend, then > run 'docker compose up -d', the node_modules directory may @@ -42,7 +46,8 @@ The frontend should now be accessible at: `http://127.0.0.1:` ## Frontend Tips -The frontend is built with React and Typescript. Here are some tips on how to work with the frontend: +The frontend is built with React and Typescript. Here are some tips on how to +work with the frontend: ### Adding Environment Variables diff --git a/docs/dev/Setup.md b/docs/dev/Setup.md index 9fa7b22aad..9735145b9c 100644 --- a/docs/dev/Setup.md +++ b/docs/dev/Setup.md @@ -17,23 +17,23 @@ - [Verify Setup](#verify-setup) - [Start Developing](#start-developing) -# Overview +## Overview -## Introduction to Field Mapping Tasking Manager Web App +### Introduction to Field Mapping Tasking Manager Web App The FMTM web app is an app that serves as a frontend for the ODK Central server, using the -[ODK Central API](https://odkcentral.docs.apiary.io/#) to allocate specific +[ODK Central API][1] to allocate specific areas/features to individual mappers, and receive their data submissions. -![1](https://github.com/hotosm/fmtm/assets/97789856/305be31a-96b4-42df-96fc-6968e9bd4e5f) +![fmtm splash screen][2] The FMTM codebase consists of: - An API backend in FastAPI (code in: `src/backend`) - A frontend website in React (code in: `src/frontend`) -### Manager Web Interface (with PC browser-friendlymap view) +#### Manager Web Interface (with PC browser-friendlymap view) A computer-screen-optimized web app that allows Campaign Managers to: @@ -41,11 +41,12 @@ A computer-screen-optimized web app that allows Campaign Managers to: - Choose task-splitting schemes - Provide instructions and guidance specific to the project - View areas that are at various stages of completion -- Provide a project-specific URL that field mappers can access from their mobile phones to select and map tasks. +- Provide a project-specific URL that field mappers can access from their mobile + phones to select and map tasks. -## Basic Tools used +### Basic Tools used -### [ODK Collect](https://docs.getodk.org/collect-intro/) +#### [ODK Collect](https://docs.getodk.org/collect-intro/) A mobile data collection tool that functions on almost all Android phones. Field mappers use ODK Collect to select features such as buildings or amenities, @@ -53,25 +54,33 @@ and fill out forms with survey questions to collect attributes or data about those features (normally at least some of these attributes are intended to become OSM tags associated with those features). -The ODK Collect app connects to a back-end server (in this case ODK Central), which provides the features to be mapped and the survey form definitions. +The ODK Collect app connects to a back-end server (in this case ODK Central), +which provides the features to be mapped and the survey form definitions. -### [ODK Central server](https://odkcentral.docs.apiary.io/#) +#### [ODK Central server](https://odkcentral.docs.apiary.io) -An ODK Central server that functions as the back end for the field data collectors' ODK Collect apps on their Android phones. Devs must have access to an ODK Central server with a username and password granting admin credentials. +An ODK Central server that functions as the back end for the field data +collectors' ODK Collect apps on their Android phones. Devs must have access to +an ODK Central server with a username and password granting admin credentials. -[Here are the instructions for setting up an ODK Central server on Digital Ocean](https://docs.getodk.org/central-install-digital-ocean/) (it's very similar on AWS or whatever) +[Here](https://docs.getodk.org/central-install-digital-ocean/) are the +instructions for setting up an ODK Central server on Digital Ocean (it's very +similar on AWS etc) -# Guide for Users +## Guide for Users -## Prerequisites +### Prerequisites - Stable internet connection. -- Mapping Knowledge (Optional): While not mandatory, having some mapping knowledge can enhance your experience with FMTM. If you are new to mapping we suggest you to read [this](https://tasks.hotosm.org/learn/map) +- Mapping Knowledge (Optional): While not mandatory, having some mapping + knowledge can enhance your experience with FMTM. If you are new to mapping we + suggest you to read [this](https://tasks.hotosm.org/learn/map) -## Steps to create a project in FMTM +### Steps to create a project in FMTM - Go to [fmtm](https://fmtm.hotosm.org/) . -- If you are new then on the top right cornor click on Sign up and create an account . Else , Sign in to your existing account . +- If you are new then on the top right cornor click on Sign up and create an + account. Else, sign in to your existing account. - Click the '+ CREATE NEW PROJECT' button. - Enter the project details. @@ -85,92 +94,126 @@ An ODK Central server that functions as the back end for the field data collecto ![Screenshot 2023-06-07 232152](https://github.com/hotosm/fmtm/assets/97789856/b735a661-d0f6-46b8-b548-5ad7b1928480) -- Select Form . +- Select Form. ![Screenshot 2023-06-07 232316](https://github.com/hotosm/fmtm/assets/97789856/475a6070-4897-4e84-8050-6ecf024d0095) - Click on Submit button. -- **Please watch the video below for more details**:point_down: - - - +- **Please watch the video below for more details** :point_down: -## Work on existing projects +### Work on existing projects -If you donot want to create a new project and wish to work on an existing project then follow the steps below: +If you donot want to create a new project and wish to work on an existing +project then follow the steps below: - Go to [fmtm](https://fmtm.hotosm.org/) . -- If you are new then on the top right cornor click on Sign up and create an account . Else , Sign in to your existing account . -- Click the button **Explore Projects** . -- Select the project you can work on . +- If you are new then on the top right cornor click on Sign up and create an + account. Else, sign in to your existing account. +- Click the button **Explore Projects**. +- Select the project you can work on. - Click on the marked area. - Click on start mapping. ![5](https://github.com/hotosm/fmtm/assets/97789856/9343a4bc-462c-44af-af93-8a67907837b3) -## Help and Support +### Help and Support -If you encounter any issues or need assistance while using FMTM, you can access the following resources: +If you encounter any issues or need assistance while using FMTM, you can access +the following resources: - Check the [FAQs](https://hotosm.github.io/fmtm/FAQ/) . - Ask your doubts in the [Slack channel: #fmtm-field-pilots](https://hotosm.slack.com/archives/C04PCBFDEGN) -## Thank you +### Thank you -We are excited to have you join our community of passionate mappers and volunteers. FMTM is a powerful platform developed by the Humanitarian OpenStreetMap Team (HOT) to facilitate mapping projects for disaster response, humanitarian efforts, and community development. +We are excited to have you join our community of passionate mappers and +volunteers. FMTM is a powerful platform developed by the Humanitarian +OpenStreetMap Team (HOT) to facilitate mapping projects for disaster response, +humanitarian efforts, and community development. -With FMTM, you have the opportunity to make a real impact by mapping areas that are in need of support. Your contributions help create detailed and up-to-date maps that aid organizations and communities in their efforts to respond to crises, plan infrastructure, and improve the lives of people around the world. +With FMTM, you have the opportunity to make a real impact by mapping areas that +are in need of support. Your contributions help create detailed and up-to-date +maps that aid organizations and communities in their efforts to respond to +crises, plan infrastructure, and improve the lives of people around the world. -Whether you are a seasoned mapper or new to the world of mapping, FMTM provides a user-friendly interface and a range of tools to make your mapping experience smooth and rewarding. You can create tasks, collaborate with other volunteers, and contribute to ongoing projects that align with your interests and expertise. +Whether you are a seasoned mapper or new to the world of mapping, FMTM provides +a user-friendly interface and a range of tools to make your mapping experience +smooth and rewarding. You can create tasks, collaborate with other volunteers, +and contribute to ongoing projects that align with your interests and +expertise. -By mapping with FMTM, you are joining a global community of dedicated individuals who share a common goal of using open data to make a positive difference. Together, we can create a more resilient and inclusive world. +By mapping with FMTM, you are joining a global community of dedicated +individuals who share a common goal of using open data to make a positive +difference. Together, we can create a more resilient and inclusive world. -Explore the projects, join tasks, and contribute your skills to help us build accurate and comprehensive maps. Don't hesitate to ask questions, seek guidance, and engage with fellow mappers through our forums and communication channels. +Explore the projects, join tasks, and contribute your skills to help us build +accurate and comprehensive maps. Don't hesitate to ask questions, seek guidance, +and engage with fellow mappers through our forums and communication channels. -Thank you for being part of FMTM. Your mapping efforts are invaluable, and we appreciate your commitment to making a difference. +Thank you for being part of FMTM. Your mapping efforts are invaluable, and we +appreciate your commitment to making a difference. Happy mapping! The FMTM Team -# Guide for Developers +## Guide for Developers -## FMTM frontend +### FMTM frontend _To view details about the frontend click [here](https://hotosm.github.io/fmtm/dev/Frontend/)_ -### Field Mapper Web Interface (with mobile-friendly map view) +#### Field Mapper Web Interface (with mobile-friendly map view) -Ideally with a link that opens ODK Collect directly from the browser, but if that's hard, the fallback is downloading a QR code and importing it into ODK Collect. +Ideally with a link that opens ODK Collect directly from the browser, but if +that's hard, the fallback is downloading a QR code and importing it into ODK +Collect. -## FMTM backend +### FMTM backend _To in details about the backend click [here](https://hotosm.github.io/fmtm/dev/backend/)_ -A backend that converts the project parameters entered by the Campaign Manager in the Manager Web Interface into a corresponding ODK Central project. Its functions include: +A backend that converts the project parameters entered by the Campaign Manager +in the Manager Web Interface into a corresponding ODK Central project. It's +functions include: - Convert the AOI into a bounding box and corresponding Overpass API query -- Download (using the Overpass API) the OSM features that will be mapped in that bounding box (buildings and/or amenities) as well as the OSM line features that will be used as cutlines to subdivide the area +- Download (using the Overpass API) the OSM features that will be mapped in that + bounding box (buildings and/or amenities) as well as the OSM line features that + will be used as cutlines to subdivide the area - Trim the features within the bounding box but outside the AOI polygon -- Convert the polygon features into centroid points (needed because ODK select from map doesn't yet deal with polygons; this is likely to change in the future but for now we'll work with points only) -- Use line features as cutlines to create individual tasks (squares don't make sense for field mapping, neighborhoods delineated by large roads, watercourses, and railways do) -- Split the AOI into those tasks based on parameters set in the Manager Web Interface (number of features or area per task, splitting strategy, etc). +- Convert the polygon features into centroid points (needed because ODK select + from map doesn't yet deal with polygons; this is likely to change in the future + but for now we'll work with points only) +- Use line features as cutlines to create individual tasks (squares don't make + sense for field mapping, neighborhoods delineated by large roads, watercourses, + and railways do) +- Split the AOI into those tasks based on parameters set in the Manager Web + Interface (number of features or area per task, splitting strategy, etc). - Use the ODK Central API to create, on the associated ODK Central server: - A project for the whole AOI - One survey form for each split task (neighborhood) - - This might require modifying the xlsforms (to update the version ID of the forms and change the name of the geography file being referred to). This is pretty straightforward using [OpenPyXL](https://openpyxl.readthedocs.io/en/stable/), though we have to be careful to keep the location within the spreadsheet of these two items consistent. - - GeoJSON feature collections for each form (the buildings/amenities or whatever) - - An App User for each form, which in turn corresponds to a single task. When the ODK Collect app on a user's phone is configured to function as that App User, they have access to _only_ the form and features/area of that task. - - A set of QR Codes and/or configuration files/strings for ODK Collect, one for each App User - -## Prerequisites for Contribution - -### 1. Review documentation + - This might require modifying the xlsforms (to update the version ID of the + forms and change the name of the geography file being referred to). This is + pretty straightforward using + [OpenPyXL](https://openpyxl.readthedocs.io/en/stable/), + though we have to be careful to keep the location within the spreadsheet + of these two items consistent. + - GeoJSON feature collections for each form (the buildings/amenities etc) + - An App User for each form, which in turn corresponds to a single task. When + the ODK Collect app on a user's phone is configured to function as that App + User, they have access to _only_ the form and features/area of that task. + - A set of QR Codes and/or configuration files/strings for ODK Collect, one + for each App User + +### Prerequisites for Contribution + +#### 1. Review documentation Don't forget to review the [Contribution](https://hotosm.github.io/fmtm/CONTRIBUTING/) @@ -178,22 +221,26 @@ guidelines and our [Code of Conduct](https://hotosm.github.io/fmtm/CODE_OF_CONDUCT/) before contributing! -Here are the steps to contribute to the frontend of Field Mapping Tasking Manager: +Here are the steps to contribute to the frontend of Field Mapping Tasking +Manager: -### 2. Fork the repository +#### 2. Fork the repository Forking creates a copy of the repository in your own GitHub account. -Go to the [Field Mapping Tasking Manager repository](https://github.com/hotosm/fmtm) and click the "Fork" button in the top right corner of the page. +Go to the +[Field Mapping Tasking Manager repository](https://github.com/hotosm/fmtm) +and click the "Fork" button in the top right corner of the page. -### 3. Navigate to your working directory +#### 3. Navigate to your working directory -Open a terminal and navigate to the directory you want to work in using the following command: +Open a terminal and navigate to the directory you want to work in using the +following command: `cd ` Make sure to replace `` with the name of your directory. -### 4. Clone the forked repository +#### 4. Clone the forked repository Clone the forked repository to your local machine using the following command: @@ -201,70 +248,100 @@ Clone the forked repository to your local machine using the following command: Make sure to replace `` with your GitHub username. -### 5. Create a new branch +#### 5. Create a new branch Create a new branch for your changes using the following command: `git checkout -b branch-name` -Make sure to give your branch a descriptive name that reflects the changes you'll be making. +Make sure to give your branch a descriptive name that reflects the changes +you'll be making. -### 6. Make changes +#### 6. Make changes Make your contribution, run tests where needed and save. -### 7. Add changes +#### 7. Add changes Add the changes you've made using the following command: `git add ` -Make sure you replace `` with the name of the file you made changes to. +Make sure you replace `` with the name of the file you made changes +to. -### 8. Commit and push +#### 8. Commit and push -Once you've added changes, commit them to your local branch using the following command: +Once you've added changes, commit them to your local branch using the following +command: `git commit -m "Add feature"` -Make sure to write a descriptive commit message that explains the changes you've made. Then, push your changes to your forked repository using the following command: +Make sure to write a descriptive commit message that explains the changes you've +made. Then, push your changes to your forked repository using the following +command: `git push origin branch-name` -### 9. Submit a pull request +#### 9. Submit a pull request Go to your forked repository on GitHub and click the "Pull requests" tab. -Change the base branch from `main` to `development`, select the branch that contains your changes from the compare branch, then click "Create pull request". -This will open a new pull request in the fmtm repository, where you can describe your changes and request that they be merged into the main codebase. - -> Note: After a PR has been approved and merged, if the branch is no longer in use, delete it both locally and remotely. Otherwise we get buried in dead branches we don't need. -> Use the following commands: -> Switch out of the branch you want to delete `git checkout `(_Replace `` with any other existing branch name_). -> Delete the branch locally `git branch -d ` and then delete the branch remotely `git push origin --delete `(_Replace `` with the name of the branch you want to delete_). +Change the base branch from `main` to `development`, select the branch that +contains your changes from the compare branch, then click "Create pull +request". +This will open a new pull request in the fmtm repository, where you can describe +your changes and request that they be merged into the main codebase. + +> Note: After a PR has been approved and merged, if the branch is no longer +> in use, delete it both locally and remotely. Otherwise we get buried in dead +> branches we don't need. +> +> Use the following commands: +> +> Switch out of the branch you want to delete: +> `git checkout ` +> +> _Replace `` with any other existing branch name_ +> +> Delete the branch locally: +> `git branch -d ` +> and then delete the branch remotely: +> `git push origin --delete ` +> +> _Replace `` with the name of the branch you want to delete_ That's it! You've now contributed to the Field Mapping Tasking Manager. -## Setup Your Local Environment +### Setup Your Local Environment These steps are essential to run and test your code! -### 1. Setup OSM OAUTH 2.0 +#### 1. Setup OSM OAUTH 2.0 -The FMTM uses OAUTH2 with OSM to authenticate users. To properly configure your FMTM project, you will need to create keys for OSM. +The FMTM uses OAUTH2 with OSM to authenticate users. To properly configure your +FMTM project, you will need to create keys for OSM. -1. [Login to OSM](https://www.openstreetmap.org/login) (_If you do not have an account yet, click the signup button at the top navigation bar to create one_). Click the drop down arrow on the extreme right of the navigation bar and select My Settings. +1. [Login to OSM](https://www.openstreetmap.org/login) (_If you do not have an + account yet, click the signup button at the top navigation bar to create one_). + Click the drop down arrow on the extreme right of the navigation bar and + select My Settings. -2. Register your FMTM instance to OAuth 2 applications. Put your login redirect url as `http://127.0.0.1:7051/osmauth/`, For Production replace the URL as production API Url +2. Register your FMTM instance to OAuth 2 applications. Put your login redirect + url as `http://127.0.0.1:7051/osmauth/`, For Production replace the URL as + production API Url -> Note: `127.0.0.1` is required instead of `localhost` due to OSM restrictions. + > Note: `127.0.0.1` is required instead of `localhost` due to OSM restrictions. -image + image -3. Right now read user preferences permission is enough later on fmtm may need permission to modify the map option which should be updated on OSM_SCOPE variable on .env , Keep read_prefs for now. +3. Right now read user preferences permission is enough later on fmtm may need + permission to modify the map option which should be updated on OSM_SCOPE + variable on .env , Keep read_prefs for now. -4. Now Copy your Client ID and Client Secret. Put them in the `OSM_CLIENT_ID` and `OSM_CLIENT_SECRET` field of your `.env` file +4. Now Copy your Client ID and Client Secret. Put them in the `OSM_CLIENT_ID` + and `OSM_CLIENT_SECRET` field of your `.env` file -#### 2. Create an `.env` File +##### 2. Create an `.env` File Environmental variables are used throughout this project. To get started, create `.env` file in the top level dir, @@ -280,36 +357,49 @@ bash scripts/gen-env.sh > `EXTRA_CORS_ORIGINS` is a set of comma separated strings, e.g.: > -## Verify Setup +### Verify Setup -### Check Deployment +#### Check Deployment -For details on how to run this project locally for development, please look at: [Backend Docs](https://hotosm.github.io/fmtm/dev/Backend) +For details on how to run this project locally for development, please look at: +[Backend Docs](https://hotosm.github.io/fmtm/dev/Backend) -### Check Authentication +#### Check Authentication -Once you have deployed, you will need to check that you can properly authenticate. +Once you have deployed, you will need to check that you can properly +authenticate. 1. Navigate to `http://api.fmtm.localhost:7050/docs` - Three endpoints are responsible for oauth - image + Three endpoints are responsible for oauth + image -2. Select the `/auth/osm_login/` endpoint, click `Try it out` and then `Execute`. - This would give you the Login URL where you can supply your osm username and password. +2. Select the `/auth/osm_login/` endpoint, click `Try it out` and then + `Execute`. + This would give you the Login URL where you can supply your osm username + and password. - Your response should look like this: + Your response should look like this: - {"login_url": "https://www.openstreetmap.org/oauth2/authorize/?response_type=code&client_id=xxxx"} + ```json + { + "login_url": "https://www.openstreetmap.org/oauth2/authorize/?response_type=code&client_id=xxxx" + } + ``` - Now copy and paste your login_url in a new tab. You would be redirected to OSM for your LOGIN. Give FMTM the necessary permission. + Now copy and paste your login_url in a new tab. You would be redirected to + OSM for your LOGIN. Give FMTM the necessary permission. - After a successful login, you will get your `access_token` for FMTM, Copy it. Now, you can use it for rest of the endpoints that needs authorization. + After a successful login, you will get your `access_token` for FMTM, Copy + it. Now, you can use it for rest of the endpoints that needs authorization. -3. Check your access token: Select the `/auth/me/` endpoint and click `Try it out`. - Pass in the `access_token` you copied in the previous step into the `access-token` field and click `Execute`. You should get your osm id, username and profile picture id. +3. Check your access token: Select the `/auth/me/` endpoint and click + `Try it out`. + Pass in the `access_token` you copied in the previous step into the + `access-token` field and click `Execute`. You should get your osm id, + username and profile picture id. -## Start Developing +### Start Developing Don't forget to review the [Contribution](https://hotosm.github.io/fmtm/CONTRIBUTING/) @@ -320,3 +410,6 @@ before contributing! Happy coding! The FMTM Developer Team + +[1]: https://odkcentral.docs.apiary.io +[2]: https://github.com/hotosm/fmtm/assets/97789856/305be31a-96b4-42df-96fc-6968e9bd4e5f