Histórico da Página

Introdução

Este estudo tem por objetivo elaborar uma proposta de modelo de trabalho para a produção e revisão de documentação relativa ao tema microsserviços. Estes documentos, quando publicados para a comunidade de desenvolvedores TOTVS, possuirão caráter prescritivo e orientativo, sendo necessário um modelo de trabalho que garanta que as informações disponibilizadas sejam válidas, consistentes e precisas.

Desenvolvimento

O ponto de partida para o desenvolvimento deste estudo foram dois modelos de documentação de considerável relevância no contexto de tecnologia da informação: RFC e JEP.

Ambos os modelos estão sendo usados a um tempo considerável (RFC, desde os anos 70; JEP, desde 2011) e tem se mostrado eficazes no que se propõem: garantir consistência nas informações publicadas através da discussão e revisão do conteúdo pela comunidade.

O estudo consistiu, basicamente, de pesquisa bibliográfica em fontes disponíveis na Internet, através de pesquisa no Google. Os links pesquisados podem ser encontrados no final deste documento, em Referências Consultadas.

Modelos pesquisados

Nos tópicos a seguir, desenvolveremos uma breve descrição do funcionamento dos modelos sugeridos para estudo.

Request for Coments (RFC)

São documentos utilizados para divulgar padrões, boas práticas e informações relativas ao funcionamento da Internet e de tecnologias associadas. As RFCs surgiram no final da década de 60, praticamente junto com a Internet.

Uma RFC pode ser elaborada por qualquer pessoa, física ou jurídica, mas a maioria é originária da IETF (Internet Engineering Task Force). Outras fontes, também chamadas streams, de RFCs são IRTF (Internet Research Task Force), IAB (Internet Architecture Board) e Independent Submission.

As RFCs também podem ser agrupadas em sub-séries: BCP (Best Current Practice), FYI (For Your Information) e STD (Standard).

O processo de elaboração de uma RFC da sub-série STD (que é descrito pela RFC 2026 ) inicia com um documento chamado Internet Draft (ID). Este documento, após revisão pela comunidade de interessados no tema e depois de ser considerado valioso e estável o suficiente, é transformado em RFC com status de Proposed Standard. Após estar tecnicamente madura, a RFC muda para Draft Standard. Quando a RFC está amplamente em uso e sua implementação é madura e estável, ela finalmente alcança o status de Internet Standard. As outras sub-séries também tem seus status, conforme definido pela RFC 2026.

Uma RFC também pode receber designações que indicam sua natureza ou seu estágio no ciclo de vida. São eles:

• Standard Tracks
• Informational
• Experimental
• Best Current Practice
• Historic
• Unknown

Por fim, uma RFC pode ter níveis de recomendação, conforme segue:

• Required
• Recommended
• Elective
• Limited Use
• Not recommended

Uma vez publicada, a RFC não pode ser alterada, no sentido de receber adições ou modificações consideráveis de conteúdo (correções tipográficas e redacionais, entretanto, são permitidas). Caso seja necessário, por exemplo, publicar uma nova versão de um protocolo descrito por uma RFC, um novo documento deve ser elaborado, o que tornará a RFC anterior obsoleta. Isso deve ser indicado em ambas RFCs,

Todas as RFCs são publicadas em formato texto plano, com limite fixo de 80 colunas (non-flowable text). Entretanto, podem ser publicadas em outros formatos (PDF, HTML, etc.), desde que haja a publicação no formato padrão.

A fonte padrão das RFCs é o RFC Editor. É atualmente o responsável pelo recebimento de submissões e pela publicação das RFCs na Internet. 

JDK Enhancement Proposal (JEP)

O objetivo primário do JEP é propor melhorias e mudanças no Java Development Kit. O conjunto de JEPs aprovados comporão o roadmap de longo prazo da JDK. Ele difere da JSR (Java Specification Request), que visa propor alterações na linguagem Java e é coordenada pelo JCP (Java Community Process). Neste sentido, pode ocorrer que uma JEP, dependendo do seu escopo, possa gerar uma JSR.

O processo foi criado em 2011 e inspirado no PEP (Python Enhancement Proposal). Comparando os dois, é possível ver muitas similaridades.

Uma JEP pode ser de um dos seguintes tipos:

• Feature: quando propõe a inclusão ou modificação de uma feature na JDK.
• Research: quando apresenta um tema para pesquisa.
• Infrastructure: quando diz respeito a infraestrutura de desenvolvimento e expedição da JDK.
• Informational: quando a JEP fornece informações sobre a JDK.
• Process: quando fornece informações sobre o próprio processo do JEP.

Em linhas gerais, uma JEP pode assumir os seguintes status:

• Draft: Quando o autor esboça a JEP e busca as revisões iniciais e consensos acerca da proposta.
• Posted: Quando a JEP entra no repositório, para mais ser avaliada por mais revisores.
• Submitted: Quando o autor entende que a JEP está pronta para ser implementada. Neste estágio, todas as possíveis lacunas foram preenchidas.
• Candidate: Quando a JEP entra no roadmap da JDK. Esta ação é tomada pelo líder da JDK.
• Founded: a JEP tem o aval de um grupo ou área para ser implementada, além de ter os recursos necessários alocados.
• Complete/Closed: a JEP é totalmente implementada e disponibilizada na JDK.
• Withdrawn: Pode ocorrer quando o autor da JEP a arquiva. Pode ser desarquivada.
• Rejected: não há entendimento de que a JEP deva ser implementada, ou o esforço não vale a pena.
• Active: Para JEPs de longa duração, como as de processo ou de informação.

As JEPs designadas para implementação são incluídas como issues no JDK Bug System.

As JEPs que estejam prontas para revisão ampliada, são enviadas por e-mail para [email protected]. Um revisor faz uma avaliação inicial e a coloca no repositório de JEPs (http://openjdk.java.net/jeps), e a partir deste ponto, ela pode ser editada pelo autor clonando o referido repositório.

As JEPs tem um template padrão que deve ser preenchido e submetido utilizando o formato Markdown.

Confluence (TDN)

Apesar de não ser exatamente um modelo de publicação e revisão de propostas, o sistema gerenciador de conteúdo em uso na TOTVS - JIRA Confluence - tem algumas features que podem agregar na proposta final de modelo de trabalho. Por este motivo, foi incluído neste estudo.

Além dos recursos de edição de páginas, a feature que pesou para considerar o Confluence na proposta de solução é o workflow. Com o workflow do Confluence, é possível realizar o controle do fluxo de revisão de um documento, até sua disponibilização para o público geral.

A instalação do Confluence que dá suporte ao Totvs Developer Network (TDN) possui alguns workflows disponíveis que podem atender a necessidade presente, além de ser possível criar novos workflows.

O suporte a Markdown é limitado no TDN. Existe uma macro - inserir markup - que permite a digitação de conteúdo em sintaxe Markdown. Este conteúdo é convertido, então, para o formato do Confluence e inserido no corpo do documento. Uma vez inserido o conteúdo em Markdown, não é possível editá-lo usando este formato.

Proposta de modelo de trabalho

Com base nos estudos realizados e visando estabelecer um ponto de partida para discussão, segue proposta de modelo para elaboração, revisão e publicação de documentos relacionados a microsserviços.

Fluxo de criação

Uma proposta de tema deve ser aberta no grupo do Ryver, em um tópico específico. Recomenda-se que o tópico tenha todo o conteúdo a ser analisado e discutido pelos demais, evitando desvios para páginas ou outros materiais externos ao Ryver. Apenas referências consultadas podem estar na forma de links dentro ou no final do texto introdutório.

Utilizar o marcador "@team" para notificar todos os integrantes do grupo. Recomendamos que os integrantes do time de Microservices do Ryver habilitem o recebimento de emails de notificação, para que fiquem cientes das postagens.

O assunto será discutido e amadurecido no tópico do Ryver até que se chegue a um consenso, que deve ser registrado no próprio tópico.

Finalizada a discussão e obtido o consenso, o autor do tópico reunirá todas as informações coletadas e elaborará um documento baseado no template abaixo, formalizando o assunto. O documento iniciará com o status Draft e será publicado abrindo-se um Pull Request no repositório de documentos, para controle das alterações, em formato Markdown.

O documento (seu link para o Pull Request no repositório) será enviado para o comitê de Microsserviços para revisão, podendo ser enviado também para outras pessoas, fora do comitê, para agregar outros pontos de vista, se for relevante. Os revisores informarão suas considerações por e-mail, e o autor do documento repassará essas observações para o documento no repositório.

Após revisão e ajustes, o autor do documento muda o status para Pronto para Publicação, sendo tudo isso postado no Pull Request do repositório de documentos.

Um ou mais membros do comitê, designados como editores, resgatarão do repositório os documentos com status Pronto para Publicação e os disponibilizarão no TDN utilizando-se a macro Inserir Marcação, opção Markdown, e copiando o conteúdo do arquivo para a caixa de digitação, conforme demonstrado abaixo.

Uma vez publicado no TDN, o documento deve ser marcado como Publicado no repositório pelos editores, os quais aprovarão o Pull Request, efetivando o documento na branch master.

Fluxo de revisão

Documentos publicados que necessitem de algum ajuste podem ser editados abrindo-se um novo Pull Request no repositório. Além dos ajustes, deve-se acrescentar ao cabeçalho o número da revisão. As alterações feitas no repositório serão repassadas ao TDN pelos editores designados.

Template do documento

Autor: <Nome e e-mail do autor do documento>

Tipo: Processo | Recomendação | Informação

Status: Draft | Pronto para Publicação | Publicado

Criação: <Data e hora de criação do documento>

Atualização: <Data e hora de atualização do documento>

Revisão: <número da revisão, depois de publicado>

Publicação: <link para o documento publicado>


Resumo/Sumário

<Descrever brevemente qual o assunto do documento>

Objetivo

<Detalhar os objetivos a serem alcançados com o documento>

Detalhamento

<Descreve em detalhes as questões inerentes ao assunto e seu desenvolvimento>

Alternativas

<Quando aplicável, indicar alternativas consideradas, pontos positivos e deficiências>

Conclusões/Considerações finais

<Registrar qual a decisão final tomada. Se foram apresentadas alternativas, 
justificar porque foram escolhidas/preteridas em relação as demais.>

Referências

<Listar materiais usados para consulta, relacionados ao tema. 
Pode ser incluído o link do tópico no Ryver.>

Considerações finais

Os processos consultados forneceram uma boa base para construção do modelo. Entretanto, absorver no processo desejado os diversos elementos encontrados poderia incorrer em excesso.

Por isso, alguns poucos elementos foram considerados, como por exemplo, a manutenção dos documentos em repositório. O uso do TDN foi mantido, com o objetivo de evitar acesso direto ao repositório de documentos, que deve ser de uso restrito ao time de microsserviços e autores convidados.

Quando for construído um portal próprio para as documentações, o TDN pode deixar de ser usado.

Apresar de ter sido cogitada a opção de se usar o workflow do TDN, a ideia é manter o documento sem o recurso, já visando a futura migração para o portal de documentos. Outro ponto a considerar, no uso do workflow, é que os revisores devem estar cadastrados no Confluence e a mudança de estado do workflow não pode ser feita pelo próprio autor do documento, a princípio.

Por fim, este documento define o processo e formato para decisões de arquitetura. Definições de plataforma serão documentadas pelos frameworks em formatos menos formais e mais objetivos.

Referências consultadas

Abaixo estão os links para os textos que serviram de base para este estudo.

Sobre a importância de documentar

https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/

Request for Comments

https://en.wikipedia.org/wiki/Request_for_Comments

http://www.tcpipguide.com/free/t_InternetStandardsandtheRequestForCommentRFCProcess-3.htm

https://tools.ietf.org/html/rfc2026

https://en.wikipedia.org/wiki/Internet_Draft

JDK Enhancement Proposal

https://en.wikipedia.org/wiki/JDK_Enhancement_Proposal

http://openjdk.java.net/jeps/1

Confluence

https://confluence.atlassian.com/doc/confluence-wiki-markup-251003035.html

https://community.atlassian.com/t5/Confluence-questions/Import-markdown-into-Confluence/qaq-p/211797