Tornar arquivos mais visíveis e seguros para interface Github

[Peter]

A ideia do repositório OSMBrasil/stable é ser um pouco também de uma interface para auditorias e visualização por leigos... Neste sentido precisamos ceder a demandas mais específicas da infraestrutura de hospedagem do git, que atualmente é o Github.

Também existem características da escolha do sistema operacional, que no caso é o Linux: onde se adota a representação do newline com \n (LF) e não com \r\n (CR LF), de modo que o git precisa fazer a conversão automática quando o colaborador for Windows.

Listando todas as dicas para já se atualizar o repositório com todas elas de uma vez, e assumirmos como padrão definitivos daí em diante:

1. Adotar como padrão de newline o padrão Linux, que é apenas caracter de LF. Para que o próprio git acate a recomendação, usar o arquivo .gitattributes indicado abaixo.

2. Não usar 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. Omitir o CRS parece ser uma recomendação geral, por exemplo da rfc5870.

3. Adotar saídas "JSON pretty" conforme padrão PostgreSQL, jsonb_pretty(). É ligeiramente gastona por encher de newlines e espaços... Mas ao menos o diff funciona (!) e usuários não acostumados com JSON (sem plugin no browser) conseguem visualizar o arquivo e as eventuais alterações.
   Uma padronização seria necessária para não ter perigo de "mudar" o arquivo sem ter alterado informação alguma, então fica esta já como recomendação definitiva justificada pela auditoria "human readable".

4. Adotar uma pasta por município (por hora são poucos municípios depois melhoramos), e dentro dela um arquivo GeoJSON por mapfeature controlada (relation, way ou node expressa como polygon, line ou point), tendo em vista que as tags ficam no arquivo GeoJSON. Centenas de arquivos relativos a mapfeatures "oficiais", controladas pela equipe curadora do município, identificadas pelo nome oficial ou Wikidata-ID... Pode-se organizar as pastas por nomes de key, exceto pelo GeoJSON do type=administrative que fica na raiz.

---

Arquivo .gitattributes recomendado:

# Plase configure your git as Linux to properly handle line endings
#  git config --global core.autocrlf input

# Set the default behavior, in case people don't have core.autocrlf set.
* text=auto

# Declare files that will always have LF line endings (Linux mode) on checkout.
* text eol=lf

# Denote all files that are truly binary and should not be modified.
*.pdf binary
*.png binary
*.jpg binary
*.zip binary

[Peter]

Mais uma sugestão/discussão: os nomes de arquivo.

Como a pasta em que vem contidos os arquivos já recebe o nome completo, sugere-se nomes mais simples e indicativos do conteúdo do próprio arquivo. Por exemplo municipio.geojson.

[Peter]

Texto de apresentação transferido para https://github.com/OSMBrasil/stable/blob/master/docs/Conventions.md