Olá! Obrigado por se interessar em contribuir com o projeto!
A contribuição sua e de toda comunidade é nossa arma secreta para desenvolver este projeto a tempo para o combate ao COVID-19. Organizando direitinho, podemos conseguir fazer juntos muito mais do que jamais seria possível fazer com nossos recursos apenas.
- Guiando sua ajuda
- No que precisamos que você contribua por aqui
- Como fazer as contribuições?
- Convenções
Você pode contribuir com este projeto de diversas maneiras.
Caso esteja meio perdido(a), criamos um formulário para ajudar você a ser direcionado rapidamente para as pessoas certas que poderão falar diretamente com você, clique aqui para acessá-lo.
Preenchendo o formulário conseguimos também nos organizar melhor para falar com todos. :)
Nesse momento é preciso PRINCIPALMENTE de contribuidores especialistas (em materiais, qualidade, regulatório e controle de sistemas eletrônicos), com possibilidade de acesso a infraestrutura adequada de testes - POR EXEMPLO, associados a centros de pesquisa, universidades e empresas com experiência em desenvolvimento de novos processos e produtos. Se você se encaixa nesse perfil e fizer contato, falaremos com você e potencialmente poderemos compartilhar informações de cunho restrito.
Entendemos que a restrição de informações vai na contramão da filosofia open source, contudo o entendimento dos coordenadores do projeto preza pela segurança das pessoas em primeiro lugar. Como a situação extraordinária que nos encontramos frente à COVID-19 instiga as pessoas a tomarem medidas extremas, nos preocupamos com o mau uso das informações deste repositório que possam colocar em risco não só o trabalho já feito até aqui, mas a vida de pessoas.
Novamente, pedimos desculpas a comunidade que efusivamente contribuiu direta ou indiretamente para este projeto desde o primeiro dia de desenvolvimento.
Caso o GitHub não seja exatamente algo estranho para você, existem quatro maneiras de contribuir com esse repositório:
- HARDWARE - baixe os arquivos, monte o protótipo, faça testes e proponha novas melhorias no modelo 3D. Consulte a seção Como contribuir com o hardware para maiores detalhes.
- SOFTWARE - faça um fork e proponha seu próprio firmware e software de interface com o usuário em seu repositório. Consulte a seção Como contribuir com o software para mais detalhes.
- DADOS - se você tiver acesso a equipamentos de medição de fluxo e/ou pressão de ar, mas principalmente associados a um pulmão de testes (ou qualquer outro equipamento que simule apropriadamente um pulmão), repita os experimentos que realizamos, melhore-os e faça outros novos experimentos que ainda não foram feitos. Consulte a seção como contribuir com dados.
- DOCUMENTAÇÃO - veja quais informações parecem estar faltando, o que poderia estar mais claro ou melhor organizado no repositório. Proponha Issues ou faça Pull-Requests com melhorias e correções. Consulte a seção Como contribuir com documentação.
Temos algumas regrinhas sobre como você deve contribuir com o repositório para tornar a sua contribuição mais eficiente para o avanço do projeto, além de criar mais integração com resto da comunidade.
Independentemente de que tipo de contribuições você pode dar, valem as regras gerais:
- Confira que não existe nenhum Pull-Request aberto buscando realizar a mesma contribuição.
- Caso em dúvida sobre a implementação, abra um Issue, mas conferindo antes os Issues existentes.
- Para criar Issues e Pull-Requests que ajudem mais eficientemente o projeto, acompanhe o debate mais recente sobre aspectos do projeto no grupo de chat do Telegram ou envie um email para a lista de emails [email protected].
- Faça um fork do repositório.
- Crie uma branch a partir da sua branch master - entenda aqui porque isso é importante
- Faça os commits na branch, introduzindo as mudanças necessárias.
- Abra um Pull Request para analisarmos o merge de sua branch na master original ou em um novo branch deste repositório.
Depois que seu Pull Request for revisado, pode ser que o merge aconteça diretamente por um dos mantenedores, ou melhorias sejam requisitadas antes de incorporá-lo.
Caso seja necessário fazer alterações no seu Pull-Request, use o rebase interativo(git rebase -i) para alterar sua branch (aqui está um blogpost sobre o assunto). E faça um force push no seu fork (git push -f <seu_fork> feature-x), para automaticamente atualizar o Pull Request. Você também pode mandar uma mensagem no Pull Request para avisar os mantenedores que uma nova versão foi enviada.
- Contribuir com o hardware significa que você vai modificar e fazer Pull-Requests dos arquivos de modelos 3D e 2D do projeto nas pastas "2D laser cut" e/ou "3D model".
- Nossos modelos foram feitos no software de modelagem 3D Fusion, da Autodesk - que é passível de uso gratuito em algumas condições. Preferimos manter o master branch usando os arquivos de modelos 3D do Fusion para evitar problemas de compatibilidade no compartilhamento dos modelos 3D entre as pessoas da comunidade.
- Contudo caso você consiga modelar apenas em outros softwares, podemos criar branches especificamente para modelos usando outras ferramentas de modelagem 3D (Solidworks, SketchUp, OpenScad, FreeCad etc) de sua preferência.
- Nesse caso, o merge com o master dependerá da conversão do modelo 3D para o formato do Fusion.
- Contudo caso você consiga modelar apenas em outros softwares, podemos criar branches especificamente para modelos usando outras ferramentas de modelagem 3D (Solidworks, SketchUp, OpenScad, FreeCad etc) de sua preferência.
- Aceitaremos apenas contribuições que se baseiam em nossos Princípios de Design.
- Dependendo do caso, podemos excepcionalmente criar branches para designs que fujam ligeiramente dos Princípios de Design.
- Caso seu Pull-Request envolva uma proposta que apesar de seguir os Princípios de Design, julguemos precisar ser validada por fabricação do hardware, ela só será aprovada para merge caso seja construída e acompanhada de Dados documentando as melhorias.
- IMPORTANTE: leia sobre essa atualização crítica sobre a manutenção do firmware do projeto neste repositório.
- Contribuir com o software significa que você vai fazer um fork do projeto e desenvolver em seu repositório os códigos de firmware do controle de pressão e software de interface com o usuário.
- Contribua com os códigos disponíveis de outras pessoas da comunidade, como descrito aqui.
- Como esse é um projeto que envolve hardware, precisamos especialmente de contribuições de software cuja funcionalidade possa ser testada por você mesmo de alguma maneira - no máximo: construindo o protótipo e contribuindo com o hardware; no mínimo: através de simulações computacionais.
- Podemos testar e estamos testando suas contribuições "na prática", mas o quão mais diferente é a sua contribuição do que já estamos desenvolvendo e testando, mais tempo levaremos tentando "rodar" o seu código no hardware, então encorajamos novamente a focar esforços no que já está sendo feito.
- IMPORTANTE: leia sobre essa atualização crítica, junto com ela retiramos os dados experimentais do projeto até que os testes sejam concluídos
- Contribuir com dados significa que você adicionará arquivos de texto, planilhas, imagens e etc na pasta Dados Experimentais
- Contribuir com dados implica em você ter capacidade de ao mesmo tempo poder contribuir com o hardware e o software, tendo ainda acesso a equipamentos para realizar medições, como pressão e vazão, reproduzindo as condições que profissionais de saúde encontrariam numa situação real. Veja, por exemplo, o Sistema de Testes que usamos.
- Antes de contribuir, veja os dados e informações que já coletamos e organizamos na Wiki do projeto.
- Procure nos Issues do projeto entradas sugerindo medições e experimentos que ainda não foram feitos.
- Para ficar mais rapidamente atualizado sobre o que nós e as pessoas da comunidade estão medindo, experimentando, propondo e discutindo, entre no grupo de chat do Telegram ou envie um email para a lista de emails [email protected].
- Contribuir com documentação significa que você alterará arquivos de texto do repositório, adicionará arquivos em diferentes locais do repositório complementando informações (como imagens, pdfs etc) e apontará melhorias necessárias nos Issues.
- Nós precisamos muito de uma documentação suficientemente detalhada sobre montagem, organização do repositório, etc. Toda ajuda neste sentido será de extrema importância para todos.
- A Wiki do projeto é o principal local de organização de informação técnicas do projeto, bem como informações adicionais relevantes.
- Você pode, por exemplo, sugerir quaisquer materiais externos ou internos (artigos, posts, reports, etc.) relativos ao projeto, que possam ser úteis para quem quer entender melhor sobre o que está sendo feito.
- Todos os textos e mensagens de commit deste repositório são escritos em Português.
- Ado criar novos arquivos, ao invés de usar espaço entre palavras, use underline: _ .
- Ao nomear arquivos, use a primeira letra maiúscula e as restantes minúsculas.
- Exceções para "arquivos-padrão" do github, como o README, LAYOUT, CODE_OF_CONDUCT, LICENSE etc.
- Todos devem seguir o nosso Código de Conduta.
Lembre-se de separar mudanças não-correlacionadas em commits separados. Isto é, se seu Pull Request irá conter, por exemplo, uma mudança no README e a adição de um novo modelo 2D, cada uma destas ações deve estar em um commit separado. Ou se você está adicionando um paragrafo sobre contribuições no README, e modificando o paragrafo de Status (para atualizá-lo), isso também corresponde a dois commits separados.
Também prezamos pelo uso de mensagens bem descritivas sobre a mudança. No último exemplo do parágrafo anterior, os dois commits poderiam ter como títulos:
- Adição ao README informações de como contribuir
- Adição do relatório de status do dia 28 de Março ao README
Não utilize mensagens genéricas como "Atualizando o README".
Quanto à formatação das mensagens de commit, seguimos as convenções descritas aqui (veja a tradução para Português aqui). Em resumo:
- A primeira linha é o título. Escreva-a resumindo as mudanças, no imperativo, e tente mantê-la em até 50 characteres.
- Use uma linha em branco entre o título e corpo.
- Use o corpo para explicar em mais detalhes o motivo da mudança, justificado em 72 colunas. Pode ser omitido caso a mudança seja trivial.
- Se o commit resolve uma issue inclua um "
Closes #<issue_id>" no final.