ReadMe

O ReadMe é um conjunto de informações de identificação e de orientação para implantação de uma aplicação. Em um repositório GIT, o arquivo que é lido para apresentar essas informações encontra-se na raiz da aplicação e possui o nome de readme.md.

O primeiro item do ReadMe deve conter um cabeçalho de nível 1 com o nome da aplicação (pode ser sua sigla ou abreviatura) e um texto descritivo indicando do que se trata a aplicação, um resumo orientando os objetivos gerais do sistema.

# Nome da Aplicação

Texto descritivo.

O uso de # indica para o interpretador do GIT que a linha se trata de um cabeçalho de nível 1.

Exemplo:

O segundo item trata das tecnologias empregadas para a correta implantação e execução da aplicação. É necessário indicar todas as ferramentas e extensões exigidas.

Este item inicia-se com um cabeçalho de nível 2 com o texto Tecnologias, seguida de texto descritivo não obrigatório, elucidando quaisquer características próprias de alguma tecnologia usada e de uma lista das ferramentas e extensões necessárias.

## Tecnologias

A aplicação é desenvolvida em Laravel.
Para mais informações, consultar a documentação no site oficial do framework.

* php: >=5.6.4
* composer: 1.6.5
* Laravel: 5.4.*

O uso de * gera uma lista não numerada na sintaxe do GIT.

Exemplo:

Neste item, deve-se indicar cada passo para que a equipe responsável possa implantar a aplicação. Deve-se assumir que o leitor precise ser informado de quaisquer conhecimentos necessários.

Os comandos propriamente ditos, devem ser circundados com três apóstrofes ```, para que o interpretador do GIT diferencie visualmente esses elementos, exemplo:

```$ php artisan migrate –seed```

O resultado será algo como:

Neste item, implantação, deve-se informar também, quaisquer arquivos de configuração próprios do framework usado tais quais o .env e o constant.ts.

Indica-se exatamente a localização destes arquivos na hierarquia de diretórios da aplicação e elenca-se cada variável que deva ser valorada e uma descrição do que representa essa variável, deve-se informar também, caso necessário, um valor que deva ser usado, quando já existente.

Estas informações devem ser apresentadas em forma de tabela com os cabeçalhos: Variável, Responsabilidade e Valor; indicado o nome da variável e a sua descrição/responsabilidade e, quando necessário, o valor que deve ser usado, respectivamente.

Um exemplo pode ser:

## Implantação

* Realizar o clone do projeto

```
git clone …
```
…

### Variáveis principais do arquivo [/.env]
| Variável | Responsabilidade | Valor |
| —— | :—— | :—— |
| `DB_CONNECTION` | Identificação do SGBD: pgsql para *POSTGRES*; mysql para *MySQL* |
| `CAS_HOST` | Endereço eletrônico do serviço de autenticação CAS. | cas.ufrj.br |

O resultado é algo análogo a:

Outros item podem ser apresentados para melhor elucidar a implantação da aplicação, porém o último item que pode estar presente no ReadMe, é o de Observações, onde deverá ser informado qualquer outro elemento importante para a correta implantação.

Neste tópico, deve ser informado também, quando necessário, a periodicidade em que o servidor deve atualizar o projeto.

Este item deve ser apresentado por um cabeçalho de nível 2 com o texto Observações.

## Observações

* É necessário solicitar permissão de acesso ao CAS para o Domínio utilizado pela aplicação. Atualmente esta responsabilidade está com a Equipe de Suporte de Macaé.

Exemplo:

O link a seguir apresenta o conteúdo de um arquivo readme.md de exemplo que pode ser usado como guia: readme.md

Ou para melhor visualização: nuvem.ufrj.br/readme.md

O GitLab utiliza a sintaxe Markdown para a apresentação do arquivo ReadMe de um projeto.

Esse sintaxe pode ser seguida através dos linkis:

• https://docs.gitlab.com/ee/user/markdown.html
• https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
• https://tree.taiga.io/support/misc/taiga-markdown-syntax/