Contribuições são Bem Vindas!

Nos deixa feliz receber todas as formas de contribuição no Hyperledger, sempre há muito o que fazer!

Antes de mais nada, leia o Código de Conduta do Hyperledger antes de participar. É importante estabelecermos esse marco civil.

Nota

Se você quiser contribuir com esta documentação, consulte o Guia de estilo para colaboradores.

Formas de contribuição

Há várias maneiras de contribuir com a Hyperledger Fabric como usuário e desenvolvedor.

Como usuário:

Como escritor ou desenvolvedor de informações:

  • Atualize a documentação usando sua experiência na Fabric, enriqueça tópicos existentes ou cria novos tópicos. Uma alteração na documentação é uma maneira fácil de começar como colaborador, facilita a compreensão e o uso de outros usuários na Fabric e amplia o histórico de confirmação de código-fonte aberto.
  • Participe de uma tradução de idioma para manter a documentação do Fabric atualizada no idioma escolhido. A documentação do Fabric está disponível em vários idiomas - inglês, chinês, malaiala e português do Brasil – então por que não fazer parte de uma equipe que mantém sua documentação favorita atualizada? Você encontrará uma comunidade amigável de usuários, escritores e desenvolvedores para colaborar.
  • Inicie uma nova tradução de idioma se a documentação do Fabric não estiver disponível no seu idioma. As equipes chinesa, malaiala e brasileira começaram assim, e você também pode! É mais trabalho, pois você terá que formar uma comunidade de escritores e organizar contribuições, mas é realmente gratificante ver a documentação da Fabric disponível no idioma escolhido.

Vá para Contribuindo com a Documentação para começar sua jornada.

Como desenvolvedor:

Criando uma conta do Linux Foundation

Para participar do desenvolvimento do projeto Hyperledger Fabric, você precisará de uma conta na Linux Foundation. Depois de ter um LF ID, você poderá acessar todas as ferramentas da comunidade Hyperledger, incluindo Gerenciador de tarefas do Jira, RocketChat, e o Wiki (apenas para edição).

Siga as etapas abaixo para criar uma conta na Linux Foundation se você ainda não tiver uma.

  1. Acesse o site Linux Foundation ID.
  2. Selecione a opção Preciso criar um ID da Linux Foundation e preencha o formulário que aparece.
  3. Aguarde alguns minutos e procure uma mensagem de email com a linha de assunto: «Validate your Linux Foundation ID email». (Valide o seu email do ID da Linux Foundation)
  4. Abra a URL recebida para validar seu endereço de email.
  5. Verifique se o seu navegador exibe a mensagem You have successfully validated your e-mail address. (Você validou com sucesso o seu endereço de e-mail).
  6. Acesse Gerenciamento de problemas do Jira <https://jira.hyperledger.org> __ ou RocketChat.

Contribuindo com a Documentação

É uma boa idéia fazer da sua primeira alteração, uma alteração na documentação. É rápido e fácil de fazer, ajuda a verificar se você possui uma máquina configurada corretamente (incluindo os pré-requisito necessários) e se familiariza com todo o processo. Use as seções a seguir para ajudar você a começar:

Governança do Projeto

O Hyperledger Fabric é gerenciado sob um modelo de governança aberta, conforme descrito no capítulo. Projetos e subprojetos são liderados por um conjunto de mantenedores. Novos subprojetos podem designar um conjunto inicial de mantenedores que serão aprovados pelos mantenedores existentes do projeto de nível superior quando o projeto for aprovado pela primeira vez.

Mantenedores

O projeto Fabric é liderado pelos mantenedores de nível superior do projeto. Os mantenedores são responsáveis por revisar e mesclar todos os patches enviados para revisão e orientam a direção técnica geral do projeto dentro das diretrizes estabelecidas pelo Comitê de Direção Técnica do Hyperledger (TSC).

Tornando-se um mantenedor

Os mantenedores do projeto, de tempos em tempos, consideram adicionar um mantenedor, com base nos seguintes critérios:

  • Demonstrado histórico comprovado de análises de PR (qualidade e quantidade de análises)
  • Demonstrando liderança intelectual no projeto
  • Demonstrado trabalho de liderança no projeto e com os colaboradores

Um atual mantenedor pode enviar uma solicitação de PR para o arquivo de mantenedores. Um Colaborador nomeado pode se tornar Mantenedor por uma aprovação majoritária da proposta pelos Mantenedores existentes. Depois de aprovado, o conjunto de alterações é mesclado e o indivíduo é adicionado ao grupo de mantenedores.

Os mantenedores podem ser removidos por renúncia explícita, por inatividade prolongada (por exemplo, 3 meses ou mais sem comentários de revisão) ou por alguma infração do código de conduta ou demonstrando consistentemente um julgamento inadequado. Uma remoção proposta também requer uma aprovação majoritária. Um mantenedor removido por inatividade deve ser restaurado após uma retomada sustentada de contribuições e análises (um mês ou mais), demonstrando um compromisso renovado com o projeto.

Cadência de liberação

Os mantenedores da Fabric estabeleceram uma cadência de liberação trimestral (aproximadamente) (consulte versões). A qualquer momento, haverá um galho de lançamento LTS (suporte a longo prazo) estável, bem como o galho mestre para os próximos novos recursos. Siga a discussão no canal #fabric-release no RocketChat.

Construindo Recurso/Propondo Aprimoramento

Primeiro, reserve um tempo para revisar o JIRA para garantir que ainda não haja uma proposta aberta (ou fechada recentemente) para a mesma função. Se não houver, para fazer uma proposta, recomendamos que você abra uma Épico ou História no JIRA, o que parecer melhor se encaixar na circunstância e anexe ou escreva um «texto» coma a proposta que indica o que o recurso faria e, se possível, como ele pode ser implementado. Também ajudaria a argumentar por que o recurso deve ser adicionado, como identificar casos de uso específicos para os quais o recurso é necessário e um caso que seria beneficiado caso o recurso fosse implementado. Depois que o registro do JIRA é criado e o «texto» anexado, ou embutido no campo de descrição ou um link para um documento acessível ao público é adicionado à descrição, envie um email de introdução para a lista de correspondência fabric@lists.hyperledger.org que o vincula o problema do JIRA e solicite um feedback.

A discussão do recurso proposto deve ser conduzida na própria página do JIRA, para que tenhamos um padrão consistente em nossa comunidade sobre onde encontrar a discussão sobre design.

Obter o apoio de três ou mais mantenedores da Hyperledger Fabric para o novo recurso aumentará bastante a probabilidade de que os PRs relacionados ao recurso sejam incluídos em uma versão subsequente.

Reunião de colaboradores

Os mantenedores realizam reuniões regulares de colaboradores. O objetivo da reunião de colaboradores é planejar e revisar o progresso de lançamentos, contribuições e discutir a direção técnica e operacional do projeto e subprojetos.

Consulte a wiki para obter detalhes da reunião dos mantenedores.

Novas propostas de recurso/aprimoramento, conforme descrito acima, devem ser apresentadas a uma reunião de mantenedores para consideração, feedback e aceitação.

Roteiro de lançamento

O roteiro de versão Épica da Fabric é mantido em JIRA.

Comunicações

Usamos RocketChat para comunicação e Google Hangouts™ para compartilhamento de tela entre desenvolvedores. Nosso planejamento de desenvolvimento e priorização é feito em JIRA, e fazemos longas discussões e tomadas de decisões na lista de email.

Guia para Contribuição

Instalar Pré-Requisitos

Antes de começarmos, se você ainda não o fez, pode verificar se possui todos os pré-requisitos instalados na(s) plataforma(s) em que você estará desenvolvendo aplicativos blockchain e/ou operando a Hyperledger Fabric.

Conseguindo ajuda

Se você está procurando algo para trabalhar ou precisa de assistência especializada na depuração de um problema ou na solução de um problema, nossa comunidade está sempre pronta para ajudar. Estamos no Chat, IRC (#hyperledger no freenode.net) e nas listas de e-mail. A maioria de nós não morde :grin: e terá prazer em ajudar. A única pergunta boba é aquela que você não pergunta. As perguntas são, de fato, uma ótima maneira de ajudar a melhorar o projeto, pois destacam onde nossa documentação pode ser mais clara.

Relatando Bugs

Se você é um usuário e encontrou um bug, envie o problema usando o JIRA. Antes de criar um novo problema no JIRA, tente pesquisar os itens existentes para garantir que ninguém mais o tenha relatado anteriormente. Se tiver sido relatado anteriormente, você poderá adicionar um comentário que também esteja interessado em ver o defeito corrigido.

Nota

Se o defeito estiver relacionado à segurança, siga o processo de relatório de erros de segurança do Hyperledger.

Se não tiver sido relatado anteriormente, você pode enviar um PR com uma mensagem de confirmação bem documentada descrevendo o defeito e a correção, ou pode criar um novo JIRA. Tente fornecer informações suficientes para outra pessoa reproduzir o problema. Um dos mantenedores do projeto deve responder ao seu problema dentro de 24 horas. Caso contrário, envie um comentário ao problema e solicite sua revisão. Você também pode postar no canal relevante da Hyperledger Fabric no Hyperledger Chat. Por exemplo, um bug de documento deve ser transmitido para #fabric-documentation, um bug de banco de dados para #fabric-ledger e assim por diante …

Enviando sua correção

Se você acabou de criar um JIRA para um bug descoberto e gostaria de fornecer uma correção, gostaríamos de recebê-la com prazer! Atribua o problema do JIRA a si mesmo e envie uma solicitação de recebimento (PR). Por favor, consulte GitHub Contributions para um fluxo de trabalho detalhado.

Corrigindo problemas e histórias de atividades

Revise a lista de problemas e encontre algo que lhe interessa. Você também pode verificar a lista «preciso de ajuda». É aconselhável começar com algo relativamente direto e viável, e que ninguém já esteja designado. Se ninguém estiver designado, atribua o problema a si mesmo. Seja atencioso e revogue a tarefa se não puder terminar em um tempo razoável ou adicione um comentário dizendo que você ainda está trabalhando ativamente no problema, se precisar de um pouco mais de tempo.

Revisando Solicitações Enviadas

Outra maneira de contribuir e aprender sobre o Hyperledger Fabric é ajudar os mantenedores na revisão dos PRs (Pull Requests) abertos. De fato, os mantenedores têm o difícil papel de revisar todos os PRs que estão sendo submetidos e avaliar se devem ser unificados ou não. Você pode revisar as alterações no código e/ou na documentação, testar as alterações e informar aos remetentes e mantenedores o que você pensa. Quando a sua revisão e/ou teste estiver concluída, responda a PR com suas descobertas, adicionando comentários e/ou votação. Um comentário dizendo algo como «eu tentei no sistema X e funciona» ou possivelmente «obtive um erro no sistema X: xxx» ajudará os mantenedores em sua avaliação. Como resultado, os mantenedores serão capazes de processar PRs mais rapidamente e todos ganharão com isso.

Basta navegar pelos PRs abertos no GitHub para começar.

Validade do PR

À medida que o projeto do Fabric cresce, também aumenta a lista de pendências de PRs abertos. Um problema que quase todos os projetos enfrentam é gerenciar esse backlog de forma efetiva e o Fabric não é exceção. Em um esforço para manter o backlog do Fabric e dos PRs de projetos relacionados gerenciáveis, estamos introduzindo uma política de validade que será aplicada por bots. Isso é consistente com a maneira como outros projetos grandes gerenciam seu backlog de PRs.

Política de Validade do PR

Os mantenedores do projeto Fabric monitoram automaticamente todas as atividades de PR quanto à inatividade. Se um PR não for atualizado em duas semanas, será adicionado um comentário de lembrete solicitando que o PR seja atualizado para tratar de quaisquer comentários pendentes ou se for abandonado para ser removido. Se um PR inativo passar mais de 2 semanas sem atualização, ele será automaticamente abandonado. Se um PR tiver envelhecido mais de 2 meses desde que foi enviado originalmente, mesmo se tiver atividade, será sinalizado para revisão do mantenedor.

Se um PR enviado tiver sido aprovado em toda a validação, mas não tiver sido revisado em 72 horas (3 dias), será sinalizado diariamente para o canal #fabric-pr-review até receber um comentário.

Esta política se aplica a todos os projetos oficiais de Fabric (fabric, fabric-ca, fabric-samples, fabric-test, fabric-sdk-node, fabric-sdk-java, fabric-gateway-java, fabric-gateway-java, fabric-chaincode-node, fabric-chaincode-java, fabric-chaincode-evm, fabric-baseimage e fabric-amcl).

Configurando o ambiente de desenvolvimento

Agora, leia construindo o projeto no seu ambiente local de desenvolvimento para garantir que tudo esteja configurado corretamente.

O que torna um PR bom?

  • Uma mudança de cada vez. Nem cinco, nem três, nem dez. Uma e somente uma. Por quê? Porque limita a área de explosão da mudança. Se tivermos uma regressão, é muito mais fácil identificar o comprometimento do culpado do que se tivermos alguma alteração composta que impacta mais.
  • Inclua um link para a história da mudança no JIRA. Por quê? Porque a) queremos rastrear nossa velocidade para julgar melhor o que achamos que podemos oferecer e quando e b) porque podemos justificar a mudança com mais eficácia. Em muitos casos, deve haver alguma discussão em torno de uma mudança proposta e queremos vincular a partir da própria mudança.
  • Inclua testes unitários e de integração (ou alterações nos testes existentes) a cada alteração. Isso também não significa apenas um teste de caminho feliz. Significa teste negativo de qualquer código defensivo para detectar corretamente os erros de entrada. Ao escrever o código, você é responsável por testá-lo e fornecer os testes que demonstram que sua alteração faz o que afirma. Por quê? Porque sem isso, não temos idéia se a nossa base de código atual realmente funciona.
  • Os testes unitários não devem ter dependências externas. Você deve poder executar testes unitários localmente com go test ou equivalente para o idioma. Qualquer teste que exija alguma dependência externa (por exemplo, precisa ser preparado para executar outro componente) precisa de um mockup apropriado. Qualquer outra coisa não é teste de unitário, é teste de integração por definição. Por quê? Porque muitos desenvolvedores de código aberto fazem o Desenvolvimento Orientado a Testes. Eles colocam uma monitoração no diretório que chama os testes automaticamente, à medida que o código é alterado. Isso é muito mais eficiente do que ter que executar uma compilação inteira entre alterações de código. Consulte a definição de teste unitário para conhecer um bom conjunto de critérios que devem ser lembrados ao escrever testes unitários eficazes.
  • Minimize as linhas de código por PR. Por quê? Os mantenedores também têm empregos diurnos. Se você enviar uma alteração de 1.000 ou 2.000 linhas de código, quanto tempo você acha necessário para revisar todo esse código? Mantenha suas alterações entre 200-300 linhas de código ou menos, se possível. Se você tiver uma alteração maior, decomponha-a em várias alterações independentes. Se você estiver adicionando várias funções novas para atender aos requisitos de um novo recurso, adicione-as separadamente com seus testes e, em seguida, escreva o código que as utiliza para fornecer o recurso. Claro, sempre há exceções. Se você adicionar uma pequena alteração e, em seguida, adicionar 300 LOC de testes, você será perdoado ;-) Se precisar fazer uma alteração que tenha amplo impacto ou um monte de código gerado (protobufs, etc.). Novamente, pode haver exceções.

Nota

Grandes PR (por exemplo, com mais de 300 LOC) provavelmente não receberão uma aprovação, e você será solicitado a refatorar a alteração para estar em conformidade com esta orientação.

  • Escreva uma mensagem de commit significativa. Inclua um título significativo de 55 caracteres (ou menos), seguido por uma linha em branco, seguida por uma descrição mais abrangente da alteração. Cada alteração DEVE incluir o identificador do JIRA correspondente à alteração (por exemplo, [FAB-1234]). Isso pode estar no título, mas também no corpo da mensagem de commit.

Nota

Exemplo de mensagem de confirmação:

[FAB-1234] fix foobar() panic

Fix [FAB-1234] added a check to ensure that when foobar(foo string)
is called, that there is a non-empty string argument.

Finalmente, seja responsivo. Não deixe que uma PR envelheça com comentários de revisão não atendidas, de forma que chegue a um ponto em que exija uma nova reformulação. Isso atrasa ainda mais a fusão e adiciona mais trabalho para você - para corrigir os conflitos de mesclagem.

Questões legais

Nota: Cada arquivo de origem deve incluir um cabeçalho de licença para a Apache Software License 2.0. Veja o modelo do cabeçalho da licença.

Tentamos facilitar ao máximo a contribuição. Isso se aplica à maneira como lidamos com os aspectos legais da contribuição. Usamos a abordagem - Developer’s Certificate of Origin 1.1 (DCO) - que é a mesma que a comunidade Linux® Kernel usa para gerenciar contribuições de código.

Simplesmente solicitamos que, ao enviar um patch para revisão, o desenvolvedor inclua uma declaração de logoff na mensagem de commit.

Aqui está um exemplo de linha assinada, que indica que o remetente aceita o DCO:

Signed-off-by: John Doe <john.doe@example.com>

Você pode incluir isso automaticamente quando confirmar uma alteração no seu repositório git local usando git commit -s.