forked from Terrastories/terrastories
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
201 documentation upgrade (Terrastories#211)
* Update documentation files. * Create terrastories.gif * Update README.md * Update SETUP.md * Update README.md * Update README.md * Update README.md
- Loading branch information
1 parent
d7e14d6
commit 9559476
Showing
4 changed files
with
138 additions
and
70 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,48 @@ | ||
|  | ||
|
|
||
| **TerraStories** is an application designed to help communities map and access their own place-based storytelling. The project to develop this application was initiated by the [**Amazon Conservation Team**](https://amazonteam.org) (ACT), an organization who partners with indigenous and other traditional communities in the Amazon rainforest to help them protect their ancestral lands and traditional culture. The application is developed to be entirely open source and offline-compatible, so that it can be used by communities in the most remote locations of the world. It is a Dockerized Rails App that uses [**Mapbox**](https://mapbox.com) to help users locate content geographically on an interactive map. A team is attempting to finish this app at **Ruby by the Bay 2019**: https://rubybythebay.org/ and **Ruby for Good 2019**: https://rubyforgood.org/2019 | ||
| ## Table of Contents | ||
|
|
||
| ## How to Contribute | ||
| We ♥ contributors! By participating in this project, you agree to abide by the Ruby for Good [Code of Conduct](CODE_OF_CONDUCT.md). We welcome all types of contributions, but any pull requests that address open issues, have test coverage, or are tagged with the next milestone will be prioritized. | ||
| 1. [About Terrastories](#about-terrastories) | ||
|
|
||
| 2. [Our vision](#our-vision) | ||
|
|
||
| 3. [How to set up Terrastories](#how-to-set-up-terrastories) | ||
|
|
||
| 4. [How to contribute](#how-to-contribute) | ||
|
|
||
| ## About Terrastories | ||
|
|
||
| **First:** if you're unsure or afraid of *anything*, just ask or submit the issue or pull request anyways. You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that. | ||
| **Terrastories** is a geostorytelling application built to enable local communities to locate and map their own oral storytelling traditions about places of significant meaning or value to them. Community members can add places and stories through a user-friendly interface, and make decisions about designating certain stories as private or restricted. It is a dockerized Rails app that uses [**Mapbox**](https://mapbox.com) to help users locate content geographically on an interactive map. Terrastories is designed to be entirely offline-compatible, so that remote communities can access the application entirely without needing internet connectivity. | ||
|
|
||
| ## Steps to Contribute to Terrastories | ||
| **Step 1: Find an issue to work on** | ||
| Visit our [issues page](https://github.com/rubyforgood/terrastories/network/members) and find an issue you'd like to work on that hasn't already been claimed (It has been claimed if you see someone else's picture on it and it is assigned to someone else, or if you see someone's comment on the issue page saying they are claiming it). Comment on the issue that you have claimed it and will be working on it. An admin will add you as the assignee. | ||
| The Terrastories interface is principally composed of an interactive map and a sidebar with media content. Users can explore the map and click on activated points to see the stories associated with those points. Alternatively, users can interact with the sidebar and click on stories to see where in the landscape these narratives took place. Through an administrative back end, users can also add, edit, and remove stories, or set them as restricted so that they are viewable only with a special login. Users can design and customize the content of the interactive map entirely, and the interface itself is customizable with a color scheme and design reflecting the style of the community. | ||
|
|
||
| **Step 2: Fork the repo** | ||
| Click the "fork" button in the upper right of the Github repo page. A fork is a copy of the repository that allows you to freely explore & experiment without changing the original project. You can learn more about forking a repo in [this article](https://help.github.com/articles/fork-a-repo/). | ||
|  | ||
| ###### *Terrastories: Matawai Konde 1.0 (October 2018)* | ||
|
|
||
| **Step 3: Create a branch** | ||
| Checkout a new branch for your issue - this branch can be named anything, but we encourage the format `XXX-brief-description-of-feature` where `XXX` is the issue number. | ||
| The project to develop this application was initiated by the [**Amazon Conservation Team**](https://amazonteam.org) (ACT), an organization who partners with indigenous and other traditional communities in the Amazon rainforest to help them protect their ancestral lands and traditional culture. The first version of the application was built for a Surinamese community called the Matawai, and is in a near-finalized state. In 2019, a team is planning to finish a public SaaS version at **Ruby by the Bay 2019**: https://rubybythebay.org/ and **Ruby for Good 2019**: https://rubyforgood.org/ | ||
|
|
||
| **Step 4: Happy Hacking!** | ||
| Follow the instructions in the [SETUP.md](SETUP.md) to set up your local environment. Feel free to discuss any questions on the issues as needed, and we will get back to you! Don't forget to write some tests to verify your code. Commit your changes locally, using descriptive messages and please be sure to note the parts of the app that are affected by this commit. | ||
| ## Our vision | ||
|
|
||
| **Step 5: Pushing your branch and creating a pull request** | ||
| Make sure the tests pass! Run the current test suite with `docker-compose exec rails bundle exec rake test` If any tests break, be sure to fix them. Make a final commit if you've made more changes to fix the tests. Then, push your branch up and create a pull request. Please indicate which issue your PR addresses in the title. | ||
| Somewhere, in a remote part of the world, stories are being shared in a village in the traditional way they always have; by the elders, sitting by the fire at night, duly passing along oral histories about their homelands that they learned from their ancestors, for the benefit of the younger community members sitting nearby. But something has changed. There are less youth around. Many have left the village to go work in nearby mining and logging concessions that are destroying the homelands. The few that remain are only passively listening, more engrossed in their phones. Without a proper listener, the words of the elders are ineffective, and they vanish in the air. Soon, the elders will pass along too, and with them their vast and ancient ancestral wisdom. | ||
|
|
||
| ## Squashing Commits | ||
| Squashing your own commits before pushing is totally fine. Please don't squash other people's commits. (Everyone who contributes here deserves credit for their work! :) ). Also, consider the balance of "polluting the git log with commit messages" vs. "providing useful detail about the history of changes in the git log". If you have several (or many) smaller commits that all serve one purpose, and these can be squashed into a single commit whose message describes the thing, you're encouraged to squash. | ||
| One concerned community member, Maaike, decides to take action. Maaike has lived equal parts in the modern city and in the village, and is fluent in both worlds. She knows the power that digital media and the internet hold for preserving knowledge and for captivating the youth. She realizes that the words of the elders demonstrate the importance of caring for and protecting the community’s homelands, instead of permitting outsiders to destroy it. So, Maaike starts videorecording the elders to ensure that their stories live on for future generations. But she needs a way to show to the community, and to the outsiders, how the elders’ knowledge maps onto the homelands, which are being threatened. The traditional leadership is calling meetings in the village to discuss important matters about the future, but there is no internet there to stream videos or zoom in on digital maps. | ||
|
|
||
| There's no hard and fast rule here about this (for now), just use your best judgement. | ||
| Back in the city, Maaike approaches a geographer, Maria, for help. In the past, Maria has worked with the community to make some maps showing their ancestral sites and local place names. Maria tells Maaike about a new application called Terrastories that can work entirely offline, and which she can use to manage the video recordings and pin them to points on the map. Maaike is intrigued, but apprehensive; while she knows how to use a computer to check email or Facebook, she has no technical background in the least. Maria assures her that she won’t need any of that, at all; in fact, while she herself has some knowledge of software used to make maps, she is not a technical person either, and it will be her first time using Terrastories too. | ||
|
|
||
| ## Code Reviews & Pull Request Merging | ||
| Once you've submitted a pull request, a core contributor will work with you on doing a code review (typically pretty minor unless it's a very significant PR). If the reviewer gives a ✅ to the PR merging, then huzzah! Merge into master! If your feature branch was in this main repository (and not forked), please delete your branch after it has been merged. | ||
| They decide to do it together. Maria uses a platform called Mapbox Studio to lay out some of the community’s mapping data. Following the instructions, she downloads the Terrastories software onto Maaike’s laptop. She also downloads a map style file from Mapbox Studio, which she places in a designated area in the Terrastories files directory. From there, she double clicks the install file, which automatically sets up Terrastories on Maaike’s laptop with the map files that Maria customized in Mapbox Studio. Upon installation, they visit https://terrastories.io in the browser, and are welcomed by the Terrastories home screen. They click enter and see the mapping data laid out, ready for usage. | ||
|
|
||
| ## Stay Scoped | ||
| Try to keep your PRs limited to one particular issue and don't make changes that are out of scope for that issue. If you notice something that needs attention but is out-of-scope, put a TODO, FIXME, or NOTE comment above it. | ||
| From here, Maaike can take over. The instructions provide a startup login to enter the administrative back end. She logs in and new options appear on the interface to add and edit new stories. She attaches her external drive, and uses the user-friendly interface to upload videos and pin them to places on the map. Suddenly, the map is coming to life with the recordings of elders telling stories about the homelands. She can customize the interface with colors and visuals that are representative of her community. She is also able to set up a login for the community to access the most sacred of stories, which are for the community only and not supposed to be heard by the outsiders. But she leaves some of the stories as unrestricted too, so that these can be shared with the outsiders when needed. | ||
|
|
||
| ## Technical Spike / Investigation Issues | ||
| These issues will have an `investigation` label attached to them. They are unique in that we do not have the full details on how to solve the actual issue. These are issues that require some investigation and digging into the technology to figure out the solution. What we expect to come out of these issues is a quick write up about what you were able to find in your research. This will help inform and create new issues that are better defined and have specific steps to solve the original problem. | ||
| Maaike now has a tool on her laptop that she can share with her community, and she is elated. She shows it to community members of various ages who are able to use the application’s user-friendly interface to explore the map and the recordings of oral history storytelling. The application is translated into their own language, there are clear tutorial markers indicating how to use the application, and the interface is clean and attractive. The application provides tools to filter through the stories and the mapping content. The youth get it right away, but even the elders are able to use Terrastories with some initial guidance from Maaike. | ||
|
|
||
| ## Work In Progress Pull Requests | ||
| Sometimes we want to get a PR up there and going so that other people can review it or provide feedback, but maybe it's incomplete. This is OK, but if you do it, please tag your PR with an `in-progress` label so that we know not to review / merge it. | ||
| After all this, Maaike wishes there was a way to get it on the youth’s phones more directly, too. Maria reads through the Terrastories instructions and finds there is a way to install Terrastories on a device that can broadcast a wireless signal which other devices can connect to load the application. The instructions are thorough and complete, so she feels comfortable in obtaining the hardware and installing Terrastories onto that, as well. Now, Maaike can bring back the device to the school, turn it on, and it automatically transmits a wireless signal that the youth can connect to using their phones, and freely explore the map and story recordings on their own. Maaike feels satisfied having found a tool that can easily help her community preserve and visualize their place-based oral histories without much fuss or setup. | ||
|
|
||
| ## How to set up Terrastories | ||
|
|
||
| To install, build, and run Terrastories, please visit the [Setup](SETUP.md) guide here. | ||
|
|
||
| ## How to Contribute | ||
|
|
||
| We ♥ contributors! By participating in this project, you agree to abide by the Ruby for Good [Code of Conduct](CODE_OF_CONDUCT.md). We welcome all types of contributions, but any pull requests that address open issues, have test coverage, or are tagged with the next milestone will be prioritized. | ||
|
|
||
| ## Becoming a Core Contributor | ||
| Users that are frequent contributors and are involved in discussion may be given direct Contributor access to the Repo so they can submit Pull Requests directly, instead of Forking first. You can join us in Slack [here](https://t.co/kUtI3lnpW1), and find us in the channel #terrastories! :) | ||
| Please read our [How to Contribute](CONTRIBUTING.md) guide for more information. |
Oops, something went wrong.