CONTRIBUINDO.md

Contribuindo

Qualquer pessoa pode sugerir melhoramentos ou correções de bugs para este pacote. Uma recomendação é abrir uma issue no GitHub antes, para colher a opinião da comunidade e evitar rejeições de contribuições.

Seguimos o padrão do GitHub para modificações. Modificações são feitas por meio de Pull Requests, que nos mostram quais partes do código mudaram da versão atual para a proposta de modificação.

Havendo aprovação dos mantenedores do projeto, juntamos a modificação ao código atual (merge) e lançamos novas versões de tempos em tempos.

Conhecimentos e Recomendações

O ambiente em que executamos é o Node.js que, basicamente, executa código JavaScript. Ou seja, se você tem conhecimento em JavaScript, é um primeiro passo para poder colaborar conosco. Por padrão, o Node.js vem com o NPM instalado, mas não o usamos. Usamos o Yarn, mais moderno e rápido. Você pode instalar o Yarn usando o comando abaixo (já tendo o NPM instalado):

npm install -g yarn

Feito isso, no diretório raiz do projeto, execute:

yarn

Isso deve baixar e instalar os pacotes que Delégua Node precisa para ser desenvolvido.

Delégua Node funciona em qualquer sistema operacional que tenha uma versão de Node.js compatível.

Para os fontes, usamos TypeScript (versão mais recente). Normalmente desenvolvemos em Visual Studio Code, e, ao abrir o projeto nele, já temos as configurações para depurar (debugar) Delégua Node. Outros editores podem ser usados, mas não temos arquivos de suporte a todos eles.

Nós usamos testes unitários para testar todos os componentes de Delégua Node. Nossa biblioteca de testes é a Jest: https://jestjs.io/. Não é preciso escrever testes unitários para contribuir com o pacote.

Trabalhando na sua modificação

Recomendamos fazer um fork do projeto (ou seja, uma cópia em separado), modificar essa cópia e abrir uma Pull Request da sua cópia para o repositório oficial. Este vídeo pode ajudar.

Ao abrir uma Pull Request, fazemos alguns testes automatizados para verificar se sua modificação tem ou não problemas. Você pode fazer os mesmos testes no seu ambiente local usando o comando:

yarn testes

Isso testa a modificação com exemplos de dialetos e situações de execução que temos no repositório. Para testar outros aspectos, use:

yarn testes-unitarios

Trabalhando com pacotes linkados

Este pacote agrega outros, como o núcleo de Delégua e dialetos, que podem fazer parte do monolito do núcleo ou serem implementados em pacotes separados. Pode ser interessante, juntamente com as modificações deste pacote, alterar fontes de outros pacotes dependentes, como o próprio núcleo de Delégua.

Para isso, você precisará clonar este repositório e os repositórios dependentes. Em cada repositório dependente, utilize o comando:

yarn link

Isso cadastra o repositório como um link simbólico. Para considerar este link simbólico neste repositório, utilize o comando:

yarn link "@designliquido/nome-do-pacote"

Por exemplo, se formos linkar o núcleo de Delégua, usamos:

yarn link "@designliquido/delegua"

Testando o servidor do depurador

Para testar o servidor do depurador, para depuração remota, execute:

yarn testes:servidor-depuracao

Abra outra shell (PowerShell, bash, etc.) e execute:

nc localhost 7777

Para desenvolvimento em Windows, caso o Netcat (nc) não esteja disponível, pode-se instalá-lo de duas formas:

• Cygwin
• Nmap