Skip to end of metadata
Go to start of metadata

Módulos JavaUtils precisam ser auto-contidos?

Não. Eles podem depender de outras bibliotecas internas ou externas ao Tecgraf. Porém, as dependências devem ser estudadas e bem sintonizadas.

Um módulo JavaUtils pode depender de outro módulo JavaUtils?

Sim, pode (conforme pergunta anterior). No entanto, vale a pena sempre verificar as consequências e a real necessidade disso. Atualmente, só existe um caso deste tipo até o momento (julho de 2014): a dependência de módulos para o CORE (considerado um artefato mais básico). Outros casos podem ser necessários, mas devem ser julgados com parcimônia.

Como baixar os fontes e compilar um módulo?

Basta acessar o SVN (subversion) do projeto e compilar usando o maven. Existe um procedimento para isso na documentação do projeto.

Veja a seção de procedimentos.

Eu posso commitar uma correção em módulos do JavaUtils?

Sim, desde que sejam observados os itens do procedimento na documentação do projeto.

Veja a seção de procedimentos.

Eu posso gerar uma nova versão de módulo JavaUtils?

Sim, desde que sejam observados os itens do procedimento na documentação do projeto.

Veja a seção de procedimentos.

Eu observei que existem certas convenções nas issues do Jira do JavaUtils. Eu devo segui-las?

Sim.

Existem detalhes nas issues do Jira que são apenas convenções (fortemente baseadas em motivos históricos). Porém, existem alguns padrões que, efetivamente, contribuem para a automatização de processos e levantamento mais preciso de informações do estado geral do projeto. Os procedimentos descrevem os detalhes que efetivamente precisam ser feitos por todos os desenvolvedores. Portanto, leia-os com atenção.

Apenas como resumo, podemos citar alguns itens importantes nas issues:

  • Toda issue tem seu componente Jira associado ao respectivo módulo JavaUtils;
  • Toda issue tem um system-version relativo à versão aonde a necessidade (ou bug) foi detectada;
  • Toda issue tem relacionamentos aos commits feitos em função dela. Isso é determinado pelos textos descritivos dos commits conforme o padrão "[JUUTILS-XXX]".
  • Toda issue, quando migrada para o estado closed ou resolved, indica no atributo fix-for no Jira a versão aonde a mudança ficará disponível.

Como eu posso descobrir, sem erros, quais módulos existem?

Como cada módulo tem um SVN próprio no JavaUtils, pode-se fazer um list do subversion para verificar. Cada diretório encontrado vai corresponder a um módulo.

Por exemplo:

[user@host] svn list https://subversion.tecgraf.puc-rio.br/engdist/javautils
ant/
concurrent/
configurationmanager/
core/
excel/
gui/
jexpression/
maven/
parsers/
pdfviewer/
version/
xml/

 

Existe um módulo maven que não tem código-fonte dentro. O que é isso?

O módulo maven é apenas um local de armazenamento do parent-pom de todos os módulos -- que são artefatos maven. Isto garante uma maior uniformidade nos processos de compilação, empacotamento e deploy das bibliotecas do JavaUtils. E implica que todos os módulos sigam um padrão de codificação e estruturação. Essa estruturação fica mais clara quando se lê os detalhes dos procedimentos.

Eu sou obrigado a usar maven para produzir um novo módulo?

Até a presente data, todos os módulos são tratados desta forma. Isto tem produzido uma uniformidade importante para o projeto. Logo, pode-se assumir que maven é um requisito para a criação de um módulo.

Eu preciso ser um maven-expert para trabalhar no JavaUtils?

Não. A ideia é justamente produzir procedimentos que abstraiam detalhes de maven. Porém, o conhecimento de um conjunto mínimo de comandos é necessário. O setup inicial do ambiente e do projeto pode demandar mais know-how; mas estamos todos aqui para ajudar... Em seguida, o uso é bastante trivial; basta ler e entender os procedimentos descritos na documentação.

O mínimo necessário de instalação e configuração do Maven pode ser vista aqui.

Eu achei um bug no JavaUtils. O que fazer?

A primeira coisa é procurar entender com bastante clareza se o problema é realmente originário do JavaUtils. Em caso de dúvidas, não hesite em postar o tema na lista javautils-dev para que alguém que conheça o módulo e a funcionalidade possa ajudar. Além disso, é importante ver a lista de issues abertas no Jira do projeto (https://jira.tecgraf.puc-rio.br/jira/browse/JUTILS) para evitar duplicações e até mesmo para ver se o tema já está encaminhado de alguma forma.

Uma vez constatado o problema como um novo bug, você pode cadastrá-lo no Jira do projeto relatando o contexto do erro, a pilha de execução (se for o caso), o resultado esperado/obtido etc. Neste cadastro, é importante que a issue tenha:

  1. o componente Jira definido, pois define o módulo aonde o problema ocorreu;
  2. a versão (system-version) definida -- com base no sufixo do arquivo jar usado no seu projeto.

Dependendo da gravidade e da urgência na correção, pode ser importante deixar registrado de modo imediato o fix-for do problema. Neste caso, a pessoa que criou a issue deve deixar esse campo preenchido. E, caso não haja uma versão unreleased para tal, crie-a (ou peça a alguém com permissão para tal). A definição e a semântica de versões é descrita em um procedimento próprio.

Eu obtive uma exceção do JavaUtils. Achei um bug?

Depende do que a documentação do módulo/método informar, se ela existir.

Não havendo documentação, poste isso no javautils-dev para analisarmos. Normalmente, exceções do tipo NPE (null pointer exception), indíce inválido em array etc, quando ocorridas dentro de um método do JavaUtils, são entendidas como bug do módulo. Assumimos que o mal uso de qualquer biblioteca deve ser sinalizado com exceções e textos explicativos. Por exemplo:
throw new IllegalArgumentException("O valor não pode ser negativo");
throw new IllegalArgumentException("Parameter value cannot be null");
throw new IllegalStateException("O objeto não está inicializado");

Vou codificar uma melhoria ou nova funcionalidade no JavaUtils. Quais são os passos?

De forma geral, podemos resumir tudo nos seguintes passos (que estão detalhados nos procedimentos):

  1. Proposição na lista javautils-dev e sua consequente aprovação pelo grupo;
  2. Criação de uma ou mais issues no Jira conforme a necessidade e os padrões definidos pelo projeto;
  3. Checkout do trunk do(s) módulo(s);
  4. Codificação das melhorias e testes unitários;
  5. Execução local e testes;
  6. Commit das modificações (o texto do commit deve citar as issues associadas);
  7. Ajuste das issues como: resolved ou closed.
  8. Avaliação da necessidade da geração de uma versão imediata ou programada;
  9. Geração da nova versão.

Olhei o código e não gostei da formatação. Posso usar a minha?

Não! O código do JavaUtils, assim como de todos os outros sistemas são formatados com base em um padrão definido pelo grupo. Este padrão está bem consolidado e pode, claro, vir a ter sofrer alterações no futuro. No entanto, foge do escopo do projeto JavaUtils redefinir esta padronização.

Eu encontrei um código com pouca informação JavaDoc. Posso contribuir?

Sim! Claro! Apesar de ser uma modificação sem tanta profundidade, continua valendo a premissa que esta atividade será informada na lista javautils-dev antes de qualquer commit e que haverá uma issue para isso.

Eu encontrei um módulo (ou parte dele) sem testes unitários. Posso contribuir?

Sim. Por padrão, todos os módulos tem à disposição infraestrutura para fazer este tipo de teste com JUnit. Isso vem definido no parent-pom do módulo e define, inclusive, a versão do JUnit. Porém, como qualquer modificação, valem as premissas de postagem prévia no javautils-dev e issues no Jira.

Olhei o código e observei algumas warnings. Isto não é ruim?

A princípio sim. Mas existem diferentes tipos de gravidade quando alguma ferramenta sinaliza um aviso deste tipo. Cabe às pessoas que detectaram esse aviso fazer um primeiro julgamento e, junto com colegas, propor alguma correção no módulo. Sendo o caso de algo grave, não hesite em divulgar imediatamente no javautils-dev; afinal existem certos tipos de warnings que são, na prática, bugs!

Existe algum critério de gravidade de warnings pré-estabelecido?

Não existe, no grupo, um documento formal sobre isso. Mas existem alguns "nortes" a serem levados em conta:

  1. Existe um padrão de preferências do Eclipse do grupo. Neste arquivo, definimos a sinalização de warnings para os casos mais importantes.
  2. O uso do FindBugs traz um relatório bastante interessante de análise do código. Neste relatório, itens considerados como HIGH PRIORITY devem ser analisados e, tipicamente, considerados como candidatos a correção.
  3. Erros do tipo: "potencial null pointer access", "suspicious synchronization" etc devem ser analisados com muita cautela.

Que ferramentas o JavaUtils usa para tratamento de warnings?

O projeto usa o plug-in do FindBugs dentro de seu Hudson/Jenkins para oferecer um relatório constante do estado do trunk. Isto permite que o grupo e o desenvolvedor possam acompanhar a tendência de resolução deste tipo de problema. 

Qual a ferramenta de integração contínua do projeto JavaUtils?

Hudson em https://hudsoned.tecgraf.puc-rio.br/hudson/view/JavaUtils/  -- acessível apenas de dentro do Tecgraf.

Por padrão, existe um job para cada módulo do projeto.

 

  • No labels
Write a comment…