-
Notifications
You must be signed in to change notification settings - Fork 7
Home
Welcome to our wiki!
This is a community based on social media, born with the purpose of sharing useful and verified information in emergency.
The project is completely open and anyone can provide support using the following guidelines.
The site
Our site has been created with Github.
Get involved
In order to be added at the list of the repository developers open an issue here (qui), ask to get the access sharing your Telegram username.
Help us in improving it
This is an ongoing project. If you want to suggest improvements open an issue here (issue qui). In the same page you will see the reports entered by other users. From there you can realize what it is still possible to implement and fix.
Github repositories we are using are the following ones :
- Here This one for the website development
- Here This one for collecting and controlling the reports.
- Here This one in order to archive the open data we created
This is an opensource project composed of various integrated applications. This WIKI allows you to understand how the project is structured and how to reuse it. TerremotoCentroItalia is licensed under Creative Commons Attribution 4.0 (CC BY) whose text is available at this address. Unless otherwise specified (e.g. in the source code repositories) we ask you to comply with the criteria of this license if you reuse part of our project.
- Open an Issue
- How to use GitHub
- Working on Reports
- How the TCI method works in brief
- Convert a Google Docs document to Markdown
- How to insert an element in Press
- Develop locally on site
Issues can be used to keep track of bugs, improvements or other project requests.
All GitHub users can create an issue for a public project.
- On Github navigate to the main project page.
- Under the project name, click on the Issues tab of the project.
- Click the green "New Issue" button.
- Enter a title and description for your issue.
If you are a project maintainer you can assign the issue to someone, associate it with milestones or add a label.
You can attach a file by dragging it into the description field.
When you are done click on "Submit new issue".
Note: project maintainers can
- Create a template for issues in a project. Templates include commands that the project maintainer chooses to display in the issue description.
- Disable issues for a project.
This page is a mirror of this simple tutorial and describes the first steps to start using Github as a shared design tool.
Preamble:
This document is intended for the team working on Reports. Other users do not have permission to perform the operations described here, but they can freely leave a comment on any Issue contributing to it. For example, at this link you can see all the Reports that are still missing a position. You can suggest coordinates in a comment. A moderator will take over and apply your suggestions as soon as possible.
To join the team of Moderators, make sure you are an active member of the community, that you have contributed previously and that you enter the group chat of contributors.
Each compilation of a webform generates - after about 30 seconds - a new Issue here.
Different labels are applied to these Issues to describe their nature and approval status (which determines their final publication on the site, on bulletins, on Twitter, on Telegram channel and bot,...).
This allows everyone to collaborate in the classification, moderation and community verification of the reports. A history of all changes, operations and moderations on each Issue is available.
All it takes is an account on GitHub and a web browser, no knowledge or IT tool is required.
Reports must maintain this structure:
<pre><yamldata>
Field1: Field value1
Field2: Field value2
</yamldata></pre>
Pay attention to the following conventions when changing the content of an Issue:
- Fields that go on multiple lines must be delimited by a '. Example:
Description: 'The content of this field
spans multiple
lines
'
Field2: This field is on one line only
Attention: Fields on several lines must be delimited by ' (one at the beginning and one at the end of the field). ' is used to delimit the content of a field so it cannot be used with the normal apostrophe function inside. To use ' literally, and not as a delimiter, use \.
For example, if I wanted to write l’altro one once per line, in a multi-field field, I would have to do this:
'
L\'altro
L\'altro
'
' is used as a delimiter, while it is written \ to use it literally. In the final report it will then be shown simply as '.
- The title of the Issue becomes the title of the report on the front end.
- Changes (including publication/de-publication) appear on the final site after a maximum of 15 minutes. Use CTRL+F5 or anonymous navigation mode if you do not see any changes. If things still don't come back to you after this, proceed to open Issue and report the problem. Issue on forms (fields, structure, missing data) should be opened on [europehelp.info_forms] (https://github.com/emergenzeHack/covid19italia_form/issues).
- If you need to change the Labels that are already assigned to the Issue (the ones you see already automatically assigned) please report it here
- Do not remove the Label "form", it helps us to investigate the origin of the reports.
There are some issues that have a "Location" field, like this one.
And they end up on the map here.
If the report does not have a geolocation, the script tries to search for municipality/city names within the various fields filled in. If it finds something, it adds the location itself. When it does, the “Posizione da verificare” label is applied and the bot will comment asking you for confirmation, also giving you a link to those coordinates to see if they make sense or not.
If no position is found even after this attempt, the “Posizione Mancante” label is applied so that you can filter out any that still need it.
Therefore, issues marked with the “Posizione Mancante” label need manual intervention to add the position.
Let's take for example this report on Milan.
You can use this site: Nominatim.
In the top right corner there is a button called "Show map bounds". When pressed, a rectangle containing the coordinates appears. The most important line is "Last click".
There are two numbers, separated by a comma, are latitude and longitude. Copy them.
On the Issue, click the “...” button at the top right of the Issue, then "edit".
Now add (or edit) the ‘Posizione’ field, adding the coordinates obtained earlier:
...
Posizione: 43.768137 11.241812
The first value is Latitude, the second is Longitude (mandatory). The third and fourth indicate Altitude and Accuracy (meters). The latter two are optional.
Example:
How to know which region/province/commune has identified the system?
By looking on the site at www.covid19italia.help/issues/ (for example https://www.europehelp.info/issues/748/) if the report has a position already entered, the values ‘Region’ are those recognized based on geographical data. In this case, if there are errors, it would be more useful to fix the position.
There may be reports that have a region or province or municipality of reference, but for which it makes no sense to enter a pair of coordinates. In order for these reports to be listed on the page by region or province anyway, you can enter a field in the data of type
regione_manuale: Veneto
or
provincia_manuale: Bologna
or
comune_manuale: Cento
(Of course, since you do not have a location, the report will not be displayed on the map.)
N.B. Pay attention to the spelling of the name: it must be exactly what is used by the other reports.
Final example of a report:
<pre><yamldata>
Da_chi_offerta: comitati di quartiere
Descrizione: 'Iniziativa di cittadini e cittadine, comitati ed associazioni del Quartiere
(Centro storico) di Firenze: consegnano cibo e beni primari a chi ne fa richiesta.'
Destinatari: Consegna di cibo e generi di prima necessità
Link: https://google.it
Natura: solidale
Posizione: 43.768137 11.241812
Tipo_di_soggetto: privato
Titolo: Serve aiuto?
</yamldata></pre>
This project is "cloned" from a precedent used for the 2016 earthquake in central Italy called TCI.
TCI (terremotocentroitalia.info) is a "dynamic" site based on:
- a management of reports through issue github and from some scripts (from now on "backend")
- a cataloguing and pagination of alerts by jekyll (from now on "frontend")
The backend is directly represented by a github repo of which only the reporting part is used (you can see it here).
Pros:
- the system is robust, functional, managed by others
- very easy to use, there are several people who already have experience
- possibility to add tags to reports for cataloguing
- API to download
Against:
- to insert "machine readable" info in the reports we use YAML, which must be managed by an external editor
- if the YAML breaks, you have to intervene "by hand".
Every 5 minutes, a script:
- download all the reports from github
- decode the YAML file
- creates a JSON array that contains the alerts and the YAML file converted to JSON
- commits any differences on the GIT repo, triggering webhook and new build
Since Jekyll reads JSON directly, there are several pages that filter JSON and create HTML with lists, maps, etc.
The frameworks used are:
- bootstrap for the layout
- openlayers/leaflet for maps
Pros:
- very fast to serve
- you can rely on external sites like netlify
- practically unbreakable
Against:
- in moments of maximum usage, the update is every 5 minutes
- Processing issues on the site could be done more efficiently using github hooks and any DB to store data, so you can have faster updates. The fact remains that when the site is "stopped", it doesn't make sense to have a DB to query every moment
Here are some simple steps to convert a document made in Google Docs into a format compatible with this WIKI or as a blog post of this site so you can continue to use Google Docs if you use it normally to write and then publish content on europehelp.info
- Install the "Docs to markdown" plugin in Add-ons (from the Additional Components menu -> Install Add-ons look for "Docs to markdown".
- once the document in Google Doc is ready open the Additional Components menu select "Docs to markdown" and then "Convert".
- From the left panel press the Markdown button.
Now select all the text that is translated below...copy it with a normal "Copy" : this is your text in a Github compatible language!
Go for example to the WIKI section, create a new page by giving it a title and paste the text. At the end save the page and you will find it published.
Note: the guide on how to use "Docs to markdown" in detail can also be found here.
Done it! Easy, right?
To insert an item in the PRESS table proceed as follows:
- Go to this PRESS file
- Click the pencil icon to edit the file on Github
- Add a line to the file and insert in sequence date,source,title,comma separated links. Note: there must be no additional commas except those separating the 4 fields.
- Click on the "Commit changes" or "Propose changes" button at the bottom of the page.
- If a green "Create Pull Request" button is provided, press it and wait for the administrators to validate the change.
Done.
This short guide will explain how to create a copy of the site on your computer. In this way the changes to the code will be immediately visible in your local copy, and you can test all the improvements you are planning. Let's get started!
You will need to install some development software on your computer. On the linked pages you will find all the instructions in detail.
A minimum of familiarity with the command line terminal is required for the next steps. Nothing special, it is a tool that allows us to give commands to the computer in the form of text instead of clicking with a mouse in a window. Mac and Linux users should already have the Terminal application installed; for Windows users the git installation already includes a terminal similar to the Linux terminal.
We will also gloss over many details of git and Github, referring you to the other guide in our wiki.
The commands to insert in the terminal (also copy-paste) will be indicated as follows: example command.
First we verify that we have Ruby and bundler installed, which in turn will help us install all the dependencies we need.
On Mac with Homebrew:
brew install ruby
install the gem bundle
sudo gem install bundler:1.17.3
install command line developer tools
xcode-select --install
On Ubuntu:
sudo apt install build-essential git ruby-full ruby-bundler zlib1g-dev
Let's fork the repository on github, then clone our fork locally (remember to use your real username):
git clone https://github.com/username/covid19italia.git
If you work on data (_data/) you will need to fork and work on covid19italia_data instead of covid19italia.
Let's go inside the new folder:
cd covid19italia
We install all project dependencies:
bundle install --path vendor/bundle
Let's get the site up and running!
Let's execute, always in the folder covid19italia:
bundle exec jekyll serve
The program will then print on screen the address to open in the browser, which will be of the type http://127.0.0.1:4000/.
That's it, that's it! Good job 💪
To get a static version of the site you need to run the build process.
This is the same process that is performed when the update is released on the public version of the site.
To build locally you need to run this command:
bundle exec jekyll build
bundle update
If you run the site on a machine running Linux and developed under Windows you have to add -H 0.0.0.0 to the command you need, like:
bundle exec jekyll serve -H 0.0.0.0
In this way you can open the site from any location connected to your network and not only from the localhost. Useful to test the changes with mobile phones, tablets or other browsers.