rev docs e close #5

docs/Conventions.md

@@ -2,12 +2,36 @@
 
 Neste documento são descritas as convenções adotadas no projeto.
 
+## Apresentação e diretivas
+
+O **Projeto OSM-Stable-BR** demanda a utilização de infraestrutura [PostgreSQL](https://en.wikipedia.org/wiki/PostgreSQL),
+[PostGIS](https://en.wikipedia.org/wiki/PostGIS) e [PostgREST](http://postgrest.org/en/v6.0/),
+onde poderá, eventualmente, conviver com outros projetos OSM-Stable (no _namespace_ adota-se o prefixo `osms` antes da sigla do país).
+
+Não existem padrões muito rigoros no OSM, e diversas convenções, principalmente no que se refere às tags,
+podem variar de país para país. As ferramentas, tais como _OSMose_ e _Osm2pgsql_ são muito flexíveis tornando sua configuração complexa.
+Além disso algumas delas são conservadoras, não permitindo a adoção de tecnologias "modernas".
+A _Osm2pgsql_ por exemplo [se recusa a dar a opção JSONb](https://github.com/openstreetmap/osm2pgsql/issues/672).
+
+No Projeto OSM-Stable  adota-se a filosofia [*"Convention over configuration"*](https://en.wikipedia.org/wiki/Convention_over_configuration),
+e um modelo dados baseado em _Osm2pgsql_  e  representações JSONb controladas.
+
+As funções de exportação de dados do OSM-Stable, para seu repositório *git*, também são padronizadas.
+Foram adotados os formatos GeoJSON para geometrias e formato CSV para dados cadastrais, com representação de ponto Geohash.
+
 ## Referência estável 
-Ver https://github.com/OSMBrasil/stable/blob/master/brazil-latest.osm.md
+
+Os metadados da "cópia OSM Planet" ficam registrados no documento da raiz do repositório,
+[`brazil-latest.osm.md`](../brazil-latest.osm.md). Softwares de *parsing*  e  *templating* garantem 
+a sua expressão consistente em JSON. 
 
 ## Nomes de banco de dados
 
-Convenções para nomes e papeis nos bancos de dados.  O **Projeto OSM-Stable-BR** demanda a utilização de infraestrutura [PostgreSQL](https://en.wikipedia.org/wiki/PostgreSQL), [PostGIS](https://en.wikipedia.org/wiki/PostGIS) e [PostgREST](http://postgrest.org/en/v6.0/), onde poderá, eventualmente, conviver com outros projetos OSM-Stable (no _namespace_ adota-se o prefixo `osms`). Além disso, do ponto de vista metodológico, é requerido certo grau de encapsulamento. 
+Convenções para nomes e papeis nos bancos de dados.
+O **Projeto OSM-Stable-BR** demanda a utilização de infraestrutura [PostgreSQL](https://en.wikipedia.org/wiki/PostgreSQL),
+[PostGIS](https://en.wikipedia.org/wiki/PostGIS) e [PostgREST](http://postgrest.org/en/v6.0/),
+onde poderá, eventualmente, conviver com outros projetos OSM-Stable (no _namespace_ adota-se o prefixo `osms`).
+Além disso, do ponto de vista metodológico, é requerido certo grau de encapsulamento. 
 
 Tendo isso em vista, os nomes de bases (utilizados em `CREATE DATABASE nome_de_uma_base`) precisam ser controlados, respeitando-se as seguintes regras, finalidades e justificativas:
 
@@ -17,7 +41,43 @@ Banco | Descrição | Justificativa
 **`osms1_testing`**|Repositório rigorosamente organizado, apenas com dados selecionados. Fase *testing*, para estabilização ("quarentena") e validação humana. Requer performance e modelo dados fixado pela projeto OSM-Stable.|Faz papel "testing distribution", ou seja, permite que auditores avaliem os dados novos a tempo de fazer correções. Quando quando houver mais de um país, fará também papel de [Data Warehouse](https://en.wikipedia.org/wiki/Data_warehouse). <br/>O código "1" auxilia na manutenção e, quando preservado, na semântica de códigos (ex. porta PostgREST `3101`).
 **`osms2_stable`**|Idem base `osm2_testing`, porém correspondendo à **fase de produção**. Todos os dados foram homologados, aceitos como "estáveis e qualificados".|Requer isolamento. <br/>O código "2" auxilia na manutenção e, quando preservado, na semântica de códigos (ex. porta PostgREST `3102`).
 
-Não existem padrões muito rigoros no OSM, e diversas convenções, principalmente no que se refere às tags, podem variar de país para país. As ferramentas, tais como _OSMose_ e _Osm2pgsql_ são muito flexíveis tornando sua configuração complexa. Além disso algumas delas são conservadoras, não permitindo a adoção de tecnologias "modernas". A _Osm2pgsql_ por exemplo [se recusa a dar a opção JSONb](https://github.com/openstreetmap/osm2pgsql/issues/672). 
+## Formatos CSV e GeoJSON 
+
+A ideia do repositório *git* do Projeto OSM-Stable é ser um pouco também de uma **interface para auditoria e visualização dos dados**, principalmente para leigos (não-nerds). E essa auditoria (ou visualização) precisa ser praticável por humanos ("[_human readable_](https://en.wikipedia.org/wiki/Human-readable_medium)")  tanto via Web como via editores e visualizadores de "texto bruto",  o assim-chamado **TXT** (padrão [*plain text*](https://en.wikipedia.org/wiki/Plain_text) com caracters [UTF-8](https://en.wikipedia.org/wiki/UTF-8)).
+
+Em outras palavras, o código-fonte dos dados, que é escrito em formatos abertos tais como JSON, XML ou CSV (todos em substrato TXT) precisam ser legíveis para humanos e máquinas.
+
+Neste sentido cede-se a **demandas mais específicas da infraestrutura** *TXT* e *Web* do *git*:
+
+1. As operações *git* (pull/push) **não podem gerar falsas atualizações**, comprometendo  o repositório. Por exemplo o acréscimo de um espaço em branco entre palavras de um texto em português não altera a informação, portanto causa falsa atualização se for aceito no *git*. Para evitar o problema são adotadas as seguintes **convenções**:
+
+    1.1. O "sistema operacional de referência"  **é o Linux**, onde é adotado como padrão de [*newline*](https://en.wikipedia.org/wiki/Newline#Representation)  **apenas caracter de LF**  (diferente do Windows que é CRLF). Para que o próprio *git* acate a recomendação, usar o arquivo `.gitattributes`.<br/> Na prática isso significa que o *git* irá converter automaticamente as sequências `\r\n` (CR LF), postadas pelo  colaborador Windows, para `\n` (LF).
+
+    1.2. **Não adotar atributo _CRS_** do GeoJSON: a interface Github só aceita o *default*  dado pela omissão, apesar de ser equivalente à declaração explícita de `EPSG:4326` (ou WGS84 ou `urn:ogc:def:crs:EPSG::4326`), gerada inclusive como option no [ST_AsGeoJSON()  do PostGIS](http://www.postgis.net/docs/ST_AsGeoJSON.html).  Omitir o CRS parece ser uma recomendação geral, por exemplo da [rfc5870](https://tools.ietf.org/html/rfc5870).
+
+    1.3. Adotar saídas "JSON pretty" conforme **padrão PostgreSQL, [jsonb_pretty()](https://www.postgresql.org/docs/10/static/functions-json.html#id-1.5.8.20.55)**. É ligeiramente gastona por encher de *newlines*  e espaços... Mas com ela o *git diff*  funciona (!) e usuários não acostumados com JSON (sem plugin no browser) conseguem visualizar o arquivo e as eventuais alterações.
+
+2. Para evitar centenas ou milhares de arquivos numa mesma pasta do repositório, "poluindo" e dificultando o acesso humano através da navegação por pastas, são adotadas as seguintes convenções:
+
+    2.1. **Uma pasta por Estado**, expresso por sua abreviação de UF (unidade federal).
+
+    2.1.1. A pasta contém apenas `README.me` e (opcional) o arquivo GeoJSON, `estado.geojson`, com *mapfeature* controlada (polygon com dados da relation da região administrativa).
+
+    2.2. **Uma pasta por município**, expresso por seu "[nome lex](https://pt.wikipedia.org/wiki/Lex_(URN))" em formato Camel. Por exemplo "São Bernardo do Campo" em URN LEX de jurisdição é `sp;sao.bernardo.campo` que em Camel e adaptada para path fica  `SP/SaoBernardoCampo`.
+
+     2.2.1. A pasta contém `README.me`, o arquivo GeoJSON, `municipio.geojson`, com *mapfeature* controlada (polygon com dados da relation da região administrativa), e subpastas para<!--  lines (tipicamente ruas) e nodes (tipicamente endereços).--> [_map features_](https://wiki.openstreetmap.org/wiki/Map_Features) "oficiais", definidas e controladas pela equipe **curadora do município**.
+
+3. Para respeitar "o grande público", que não vai sequer usar [git GUI desktop](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools#Web_Interfaces) é preciso confiar o repositório a uma boa *"git Web-based Use Interface"* ([git WUI](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools#Web_Interfaces)), que atualmente é a [interface Web Github](https://help.github.com/en/github). **Convenções** adotadas para garantir consistência com a *git WUI*:
+
+    3.1. No JSON de *properties* GeoJSON, **priorizar as chave-valores de primeiro nível**. Justificativa: na visualização do GeoJSON do Github apenas atributos de primeiro nível são visíveis ao se clicar num polígono. 
+
+    3.2. ...
+
 
-No Projeto OSM-Stable  adota-se a filosofia [*"Convention over configuration"*](https://en.wikipedia.org/wiki/Convention_over_configuration), e um modelo dados baseado em _Osm2pgsql_  e  representações JSONb controladas. As funções de exportação de dados do OSM-Stable, para seu repositório *git*, também são padronizadas. Foram adotados os formatos GeoJSON para geometrias e formato CSV para dados cadastrais, com representação de ponto Geohash.
+Inicialmente, devido à demanda para prefeituras e aplicações de roteamento, apenas:
 
+* polígonos de delimitações administrativa (cidades e bairros oficiais)
+* linhas de logradouros
+* pontos de endereçamento (entrada principa do lote ou portão de entidade registrada na Wikidata - parques, hospitais, etc.).
+
+Exemplo em planilha amigável com [alguns descritores de ponto de Curitiba](https://docs.google.com/spreadsheets/d/1yKC7ZwS8kU_aHQ1raOau1x3TkmmE074G0Wu7z8XnwzQ/edit#gid=1454207711)

docs/Rationale.md

@@ -99,11 +99,11 @@ Portanto os parâmetros escolhidos (7 e 0) são adequados para o presente e o fu
 
 ### Requisito-4 do GeoJSON do município
 
-... propriedades eleitas ...
+... propriedades eleitas ... ver Conventions.md
 
-------
 
 ## Representação interna na base de dados
+
 Apesar do repositório *stable* ser totalmente independente da tecnologia que se usa para processar os dados, é interessante ressaltar algumas decisões que facilitam o processo de construção e validação dos dados.
 
 A seguir algumas decisões de projeto, baseadas na representação PostgreSQL do OSM, após carga Osm2pgsql: recomenda-se usar *tags* como JSONb ao invés de hStore.
@@ -122,3 +122,34 @@ Entre as configurações e adaptações do `osm2pgsql`, as principais opções d
    - C. Kerstiens. *"In most cases JSONB is likely what you want when looking for a NoSQL, schema-less, datatype"*; <br/>*"JSONB - In most cases"*; <br/>*"hstore - Can work fine for text based key-value looks, but in general JSONB can still work great here"*, [citusdata.com](https://www.citusdata.com/blog/2016/07/14/choosing-nosql-hstore-json-jsonb/) (2016).<br/>
    - C. Ringer. "it’s probably worth replacing hstore use with jsonb in all new applications" [blog.2ndquadrant](https://blog.2ndquadrant.com/postgresql-anti-patterns-unnecessary-jsonhstore-dynamic-columns/) (2015); "if you're choosing a dynamic structure you should choose jsonb over hstore",  [dba.stackexchange](https://dba.stackexchange.com/questions/115825/jsonb-with-indexing-vs-hstore) (2015).
    - comunidade osm2pgsql:  [issues/692](https://github.com/openstreetmap/osm2pgsql/issues/692) (em aberto), [issues/533](https://github.com/openstreetmap/osm2pgsql/issues/533) (possível reabrir se forem apresentados exemplos concretos).
+
+## Municípios do projeto-piloto 
+
+Municípios para tutoriais, testes simplificados, e projetos-piloto.
+
+A proposta do *Projeto OSM Stable BR* é ambiciosa, afinal são ~5570 municípios e armazenaríamos todos em formarmatos aberto (CSV e GeoJSON) no git. Cada município representa um coletivo de [curadores dos dados](https://en.wikipedia.org/wiki/Data_curation), que faria minimamente a seleção de dados relevante e controle de qualidade.
+
+Sendo tão abrangente, são necessários testes sobre amostragens representativas do todo. Amostragem de extremos em termos de área territorial, de densidade populacional, etc., assim como "exemplos de referência" para **tutoriais** e **projetos piloto** (futuras melhoras ou ampliações de escopo), constituindo minimamente e simulando a realidade do trabalho de uma curadoria.  
+
+### Exemplos de referência
+Foram eleitos, principalmente por terem potencias curadores já contatados, os seguintes municípios, a partir dos quais ficariam exemplificados por completo os vários aspectos do repositório:
+
+* [**Boa Vista**](../data/RR/BoaVista/municipio.geojson) (IBGE ??).
+
+* [**Curitiba**](../data/PR/Curitiba/municipio.geojson) (IBGE 4106902);
+
+* [**Jaraguá do Sul**](../data/SC/JaraguaSul/municipio.geojson) (IBGE 4208906);
+
+* [**Monteiro Lobato**](../data/SP/MonteiroLobato/municipio.geojson) (IBGE 3531704).
+
+### Casos extremos
+Com amostragem apenas parcial para testar e/ou exemplificar usos específicos do repositório, sem compromisso com completeza:
+
+* **Altamira** (IBGE 1500602), maior área (~159530 km2);
+
+* **Angra dos Reis** (IBGE ??), complexidade poligonal;
+
+* **Santa Cruz de Minas** (IBGE 3157336), menor área (~4 km2);
+
+* **São Paulo** (IBGE 3550308), maior densidade populacional.
+

src/manut/README.md

@@ -9,11 +9,12 @@ mas  pode ser necessário consultar ou rodar algum script de instalação (`/src
 
 ## Transição de teste para stable
 
+Conforme [convenções de nome de base](../../docs/Conventions.md#nomes-de-banco-de-dados) adotadas, e 
+aplicando-se boas práticas no uso do PostgreSQL e de backups de segurança,
+
 ```sh
 #  após pg_dump -s br osms2_stable | gzip > /tmp/osms_stable-br-$date.sql.gz
-psql _etc_ -c "DROP DATABASE osm_br_stable"
-psql _etc_ -c "CREATE DATABASE osm_br_stable WITH TEMPLATE osm_br_testing"
+psql _etc_ -c "DROP DATABASE osms2_stable"
+psql _etc_ -c "CREATE DATABASE osms2_stable WITH TEMPLATE osms1_testing"
 ```
 
-
-