====== 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**.

===== Organização =====
==== Introdução ====

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:

----

{{ :infotic:sistemas:captura_de_tela_de_2018-05-22_20-17-58.png?nolink&600 |}}

----

==== Tecnologias ====

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:

----

{{ :infotic:sistemas:captura_de_tela_de_2018-05-22_22-19-33.png?nolink&600 |}}

----


==== Implantação ====

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:

----
{{ :infotic:sistemas:captura_de_tela_de_2018-05-22_22-33-37.png?nolink&600 |}}
----

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:


----
{{ :infotic:sistemas:captura_de_tela_de_2018-05-22_22-47-54.png?nolink&600 |}}
{{ :infotic:sistemas:captura_de_tela_de_2018-05-22_22-48-03.png?nolink&600 |}}

----

==== Observações ====

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:

{{ :infotic:sistemas:captura_de_tela_de_2018-05-22_22-54-24.png?nolink&600 |}}

===== Exemplos =====

O link a seguir apresenta o conteúdo de um arquivo readme.md de exemplo que pode ser usado como guia: [[infotic:sistemas:implantacao:exemplo|readme.md]]

Ou para melhor visualização: [[https://nuvem.ufrj.br/remote.php/webdav/Equipe/Modelos%20de%20Documentos/Documentos%20Padr%C3%B5es/readme.md|nuvem.ufrj.br/readme.md]]

===== Referências =====

==== Markdown ====

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/