Guia para projetos Open Source

Guia para projetos Open Source

Neste artigo vou demonstrar os passos necessários para inciar um projeto Open Source com as melhores técnicas e ferramentas que estão disponíveis atualmente. Existem muitos termos em inglês e é bom você já ir se acostumando com eles.

  • Introdução
  • Yeoman
  • Coding Style
  • Linting
  • Source folder
  • Tests
  • Code Coverage
  • Continuous Integration
  • README, CHANGELOG e Badges

Introdução

Atualmente me interesso por projetos desenvolvidos em TypeScript / JavaScript relacionados à Node.js e Angular. Depois de analisar dezenas de projetos Open Source, compilei uma lista com as melhores ferramentas que os grandes desenvolvedores estão utilizando para construir seus projetos. Atualmente utilizo esse conjunto de ferramentas em meus projetos pessoais e profissionais.

Sempre que preciso iniciar um novo projeto, me deparo com a criação de uma estrutura básica de arquivos e configurações que se repetem em cada projeto. À partir dessa necessidade, decidi gerar essa estrutura de uma forma mais rápida e desenvolvi um generator para o Yeoman.

Yeoman

Yeoman é uma ferramenta que cria novos projetos de forma muito rápida. Ela possui milhares de generators, que são como modelos da estrutura inicial de um projeto. Desenvolvi o generator-oss-project para gerar o modelo de projeto Open Source para Node.js.

O código-fonte do generator está disponível no meu GitHub: https://github.com/robertoachar/generator-oss-project.

É necessário instalar o Node.js e o npm para utilizar o Yeoman.

Para instalar o generator, siga os seguintes passos:

# Instalar o Yeoman
$ npm install -g yo

# Instalar o generator
$ npm install -g generator-oss-project

Para utilizar o generator:

# Criar o diretório do projeto
$ mkdir awesome-project

# Alterar para o diretório do projeto
$ cd awesome-project

# Executar o generator através do Yeoman
$ yo oss-project

Após responder as perguntas, o generator criará os arquivos e instalará as dependências automaticamente.

OSS Project Generator
OSS Project Generator

Abra a pasta do projeto no seu editor favorito para visualizar os arquivos.

VSCode Explorer
VSCode Explorer

Nas seções seguintes vou descrever as técnicas e as ferramentas utilizadas para a criação de um novo projeto.


Coding Style

Desenvolvedores optam por utilizar diferentes editores de código e cada um desses editores possui suas próprias configurações para definir os padrões dos arquivos.

EditorConfig auxilia os desenvolvedores a definir e manter estilos de codificação consistentes entre diferentes editores. Escrevi um artigo bem interessante sobre o EditorConfig.

O generator gera um arquivo para o EditorConfig:

  • .editorconfig - define as configurações de estilos de código.
# http://editorconfig.org
root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
max_line_length = off
trim_trailing_whitespace = false

Para mais informações sobre o EditorConfig: http://editorconfig.org/.


Linting

Linting é o termo utilizado para análise estática de código e seu objetivo é encontrar problemas no código antes mesmo dele ser executado.

ESLint é uma ferramenta de linting desenvolvida especificamente para JavaScript. Possui uma grande quantidade de regras pré-definidas e é completamente customizável através de plugins.

O generator gera dois arquivos para o ESLint:

  • .eslintrc - define as regras a serem seguidas.
{
  "env": {
    "jest": true,
    "node": true
  },
  "extends": "eslint:recommended",
  "parserOptions": {
    "sourceType": "module"
  },
  "rules": {
    "indent": [
      "error",
      2
    ],
    "linebreak-style": [
      "error",
      "unix"
    ],
    "quotes": [
      "error",
      "single"
    ],
    "semi": [
      "error",
      "always"
    ]
  }
}
  • .eslintignore - define pastas e arquivos que devem ser ignorados.
node_modules

Para executar lint no código gerado:

$ npm run lint

Para mais informações sobre o ESLint: http://eslint.org/.


Source folder

A pasta src é utilizada para armazenar todos os arquivos necessários para o desenvolvimento do projeto. Nos projetos Open Source você encontrará outras pastas como doc para documentação, test para testes, entre outras.

O generator gera um arquivo para o projeto:

  • ./src/index.js - arquivo principal do projeto
'use strict';

module.exports.hello = (done) => {
  return done(null, 'It works!');
};

Tests

Testes são extremamente importantes para você não quebrar seu código. Todos os melhores projetos Open Source possuem testes. Como boas práticas, os testes são armazenados na pasta ./test.

Jest é uma solução de testes completa desenvolvida e utilizada pelo Facebook. Além de executar os testes, a solução é capaz de realizar Code Coverage.

O generator gera um arquivo para o Jest:

const lib = require('../src');

describe('TESTS', () => {

  test('Basic test', (done) => {
    lib.hello((err, message) => {
      expect(err).toBeNull();
      expect(message).toBe('It works!');

      done();
    });
  });

});

Para executar apenas os testes:

$ npm run jest

Para executar o linting + os testes:

$ npm test

Demonstracão do Jest sendo executado.

Jest
Jest

Para mais informações sobre o Jest: https://facebook.github.io/jest/.


Code Coverage

Code Coverage ou cobertura de código é uma medida utilizada para identificar a porcentagem de código que foi executado em um determinado teste. Um projeto com maior cobertura de código tem menor chance de conter bugs.

O Jest é capaz de realizar cobertura de código utilizando jest --coverage como parâmetro. O resultado da cobertura de código é enviada para o Coveralls através do Travis.

Coveralls é um serviço que rastreia a cobertura de código ao longo do tempo e garante que todo novo código esteja totalmente coberto.

Para executar os testes com cobertura de código:

$ npm run coverage

Para enviar o relatório de cobertura de código para o Coveralls:

$ npm run coveralls

Demonstracão do Jest sendo executado com Code Coverage.

Coverage
Coverage

Para mais informações sobre o Coveralls: https://coveralls.io/.


Continuous Integration

Continuous Integration ou Integração Contínua é o processo de integração e testes de um novo código com o código atual. Ele garante que o novo código só será incorporado ao código atual se os testes forem satisfeitos. Caso os testes falhem, será necessário modificar o novo código e submetê-lo novamente ao processo de Continuous Integration.

Travis, CircleCI e AppVeyor são plataformas de Continuous Integration e possuem integração com GitHub e BitBucket. Travis e CircleCI são executados em ambiente Linux e AppVeyor é executado em ambiente Windows. Travis é o responsável por enviar o resultado do Code Coverage para o Coveralls.

O generator gera três arquivos para o Continuous Integration:

  • .travis.yml - define as configurações de execução do Travis:
language: node_js

node_js:
  - "6"

install:
  - npm install

script:
  - npm test

after_script:
  - npm run coveralls

notifications:
  email:
    on_success: never
    on_failure: always
  • circle.yml - define as configurações de execução do CircleCI:
machine:
  node:
    version: 6.10.3

dependencies:
  override:
    - npm install

test:
  override:
    - npm test
  • appveyor.yml - define as configurações de execução do AppVeyor:
environment:
  nodejs_version: "6"

install:
  - ps: Install-Product node $env:nodejs_version
  - npm install

test_script:
  - node --version
  - npm --version
  - npm test

build: off

Para mais informações sobre o Travis: https://travis-ci.org/.
Para mais informações sobre o CircleCI: https://circleci.com/.
Para mais informações sobre o AppVeyor: https://www.appveyor.com/.


README, CHANGELOG e Badges

README.md é o ponto de entrada para qualquer projeto Open Source. Um bom README contém as seguintes seções abaixo:

  • Nome do Projeto
  • Badges (Medalhas)
  • Descrição
  • Instruções para instalação
  • Instruções de utilização
  • Configurações para o ambiente de desenvolvimento
  • Autor
  • Licença

CHANGELOG.md é o arquivo responsável por relacionar as alterações que foram feitas ao código atual. Os seguintes tipos de mudanças são os mais encontrados em grandes projetos.

  • Features ou novas funcionalidades
  • Improvements ou melhorias
  • Bugs fixes ou correções

Badges ou medalhas são uma representação visual da situação de um repositório. É uma prática extremamente comum nos maiores projetos que analisei até hoje. As badges exibem informações como:

  • Status da Build do Travis
  • Status da Build do AppVeyor
  • Status da Build do CircleCI
  • Status do Coveralls
  • Versão do projeto no npm
  • Tipo de Licença

Demonstração do README com as Badges.

Badges
Badges

Conclusão

Agora você não tem mais desculpas para iniciar seu próprio projeto Open Source ou fazer parte de um disponível na Internet. Basta instalar o generator e começar a escrever seu código.

O que mais me surpreende no mundo Open Source é a quantidade de coisas que aprendo em tão pouco tempo. O GitHub é o melhor lugar pra encontrar código de qualidade e escrito por desenvolvedores experientes. Faça como eu e mergulhe de cabeça, garanto que não irá se arrepender.

Jey, obrigado mais uma vez!

Vamos em frente!

"Talk is cheap. Show me the code." - Linus Torvalds
Roberto Achar

Sobre Roberto Achar

Roberto Achar é Full Stack Web Developer e fascinado pelo mundo Open Source. Gosta de escrever sobre Node.js, TypeScript, JavaScript e Angular. Nas horas vagas joga video-game, é marido e pai do Dudu.

Autor no iMasters

Follow @robertoachar

São Paulo, Brasil

Comentários