Get best of the week

Guias de código aberto: lançando um projeto de código aberto



Prefácio do tradutor


Há alguns meses, no Github, deparei-me com o link "Guias de código aberto" e não consegui sair. Em algum lugar de uma semana, li cuidadosamente todas as 10 seções. Claro, eu já sabia sobre código aberto: li vários artigos (por exemplo, “Entenda o código aberto” ), usei esses projetos em meu trabalho, endereçava perguntas às comunidades, relatava bugs, vasculhava questões e até tentava desajeitadamente depois melhore, pelo menos a documentação. E, claro, eu estava de coração com esses caras que compartilham software e conhecimento sobre o seu uso. No entanto, o conceito de código aberto era bastante vago e fragmentário. E este artigo adicionou clareza.

Além disso, eu tinha alguns projetos que planejava lançar nesse formato, com a esperança de apoio da comunidade, e com muitos medos e dúvidas, e novamente este artigo me ajudou a estabelecer minhas intenções e sugeriu etapas práticas.

Independentemente da sua atitude em relação ao código aberto, acho que você encontrará nesta série de 10 artigos muitas idéias e fatos interessantes: organizacional, psicológico, jurídico, ético e técnico.

Eu deixei esse não programador ler este texto, eles disseram que entenderam tudo. E no título do artigo, deliberadamente, coloquei a "fonte" sem o "código", porque esse tópico é relevante não apenas para programadores, mas para quase qualquer atividade intelectual no formato de um projeto aberto.

Este manual também é de código aberto e já foi traduzido para 14 idiomas. Tive a honra de adicionar um fio russo e uma tradução do primeiro artigo. Pretendo continuar a traduzir artigos por semana. Se alguém quiser se conectar, aqui está o repositório: Guias de código aberto .

Se de repente alguém precisar de um protetor de tela a partir do cabeçalho do artigo (ilustrações + nomes em russo), ele estará em um layout no codesandbox.io .

Seleção de termos


Peço desculpas antecipadamente pelas falhas na tradução. Alguns termos aparentemente banais não são tão fáceis de entender em russo. Por exemplo, para contribuir, receber solicitação, emitir, eu traduzi frequentemente como "participe do projeto, proponha correções e faça uma pergunta". Eu deixei o código aberto em inglês até agora. Já fiz um comentário e enviei um link para o dicionário de termos do Github . Não gostei da abundância de transliteração lá. Se todos esses ishis, pullrequest, push, pool, fork forem incluídos no artigo, ele se tornará incompreensível para todos que não trabalharam com o Github.

Sim, o problema pode ser uma pergunta, uma tarefa, um relatório de erro, uma sentença etc., e é difícil encontrar uma palavra em russo que transmita todos esses significados. Mas a questão da palavra em inglês também não tem um significado particularmente amplo, apenas os criadores e usuários do Github têm essa amplitude. Se queremos dizer com as palavras "abrir uma pergunta no Github" que essa pergunta pode ser muito diferente (bug, pergunta, solicitação de ajuda, tarefa, ...), a palavra "pergunta" substituirá harmoniosamente a palavra "problema". Também - empurre - envie, puxe - aceite, bifurque - ramifique, etc. Não é a palavra em si que importa, mas o significado que concordamos em colocar nela. Os britânicos, que primeiro encontraram o termo questão no Github, também precisam primeiro ler uma descrição de todos os seus possíveis significados na estrutura deste sistema.Enquanto isso, considero a clareza uma prioridade para o número máximo de pessoas que não trabalharam com o Github. De qualquer forma, a seleção de termos está em processo e a tradução inteira, como a original, é de código aberto, assim como os pull-quests e o open com ish.


: ?
«open source»?
?
Open source — ?

open source ?



open source

README






, ( ) !






: ?


Então, você está pensando em lançar seu projeto de código aberto? Parabéns! O mundo aprecia sua participação. Vamos falar sobre o que é código aberto e por que as pessoas fazem isso.

O que significa código aberto?


Quando o código do projeto é aberto, significa que qualquer pessoa é livre para usar, estudar, modificar e distribuir seu projeto para qualquer finalidade. Essas permissões são concedidas através de uma licença de código aberto .

A vantagem do código aberto é que ele reduz as barreiras na escolha do seu programa e colaboração, permitindo que as pessoas distribuam e melhorem rapidamente os projetos. Além disso, oferece aos usuários a capacidade de controlar o código, em vez de fechado. Uma empresa de software de código aberto (software) pode contratar alguém para fazer melhorias no software, em vez de confiar apenas na decisão do fornecedor de software livre.

Software livre refere-se aos mesmos projetos quesoftware de código aberto (o código aberto) . Às vezes, você pode encontrar combinações destes termos : “Software livre e de código aberto” (software livre e de código aberto FOSS ou software livre, gratuito e de código aberto FLOSS). As palavras livre e livre aqui significam "livre", não "livre" .

Por que as pessoas abrem seu trabalho?


avatarUma das maiores recompensas que recebi do código aberto é o relacionamento que foi estabelecido com outros desenvolvedores que estão enfrentando os mesmos problemas que eu.
@ kentcdodds , “Como foi bom para mim entrar no código aberto”

Há muitas razões pelas quais um indivíduo ou organização abre a fonte de seu projeto. Aqui estão alguns deles:

  • : Open source . , Exercism, 350 .
  • : Open source , . -. WordPress, , b2.
  • Transparência: qualquer pessoa pode verificar se há erros e inconsistências em um projeto de código aberto. A transparência é importante mesmo no nível estadual. Por exemplo, o governo búlgaro e os Estados Unidos legislaram a transparência para setores como bancos, saúde e software de segurança como o Let's Encrypt .

O código aberto é aplicável não apenas ao software, mas a todo o resto: de conjuntos de dados a livros. Na revisão do GitHub, você pode obter mais idéias sobre o que pode ser sensível demais.

O código aberto é gratuito?


O código-fonte aberto gratuito é um dos seus maiores benefícios, mas não é o único, mas sim um subproduto do seu valor combinado.

Como uma licença aberta implica que qualquer pessoa possa usar, modificar e distribuir seu projeto para quase qualquer finalidade, na maioria dos casos, isso implica gratuitamente. Porque, se você pedisse uma taxa, as pessoas baixariam o projeto e o usariam de graça, absolutamente legal.

Portanto, a maioria dos projetos de código aberto é gratuita, mas isso não está incluído na definição de código aberto. Existem maneiras de cobrar indiretamente por projetos de código aberto por meio de licenciamento duplo ou recursos limitados, mas eles estão em conformidade com a definição oficial de código aberto.

Devo iniciar meu projeto de código aberto?


A resposta curta é sim, porque, independentemente do resultado, lançar seu projeto é uma boa maneira de entender como o código aberto funciona.

Se você nunca executou esses projetos antes, pode estar preocupado: “o que as pessoas dirão?”, “E se ninguém notá-lo?” Se isso lhe é familiar, não se preocupe, você não é o único!

O código aberto, como qualquer trabalho criativo, seja ele de desenho ou escrita, causa entusiasmo antes de compartilhá-lo com o mundo. Mas a única maneira de aprimorá-lo é praticando, mesmo que você não tenha um público.

Se você ainda não decidiu, reserve um tempo para pensar em seus possíveis objetivos.

Estabelecimento de metas


Os objetivos ajudarão você a decidir em que trabalhar, em que desistir e onde precisa de ajuda externa. Pergunte a si mesmo: "Por que estou abrindo este projeto?" .

Não há uma resposta única para esta pergunta. Você pode ter muitos objetivos para um projeto ou projetos diferentes com objetivos diferentes.

Se seu objetivo é simplesmente mostrar seu trabalho e não houver necessidade de cooperação, você pode escrever no arquivo README. Por outro lado, se você estiver interessado em assistentes, deve investir seu tempo escrevendo documentação compreensível e cuidando dos iniciantes.
avatar UIAlertView … open source. GitHub. , , . , - . .
mavris@mavris, « : Open Source »

À medida que o projeto cresce, sua comunidade precisará de mais do que apenas código. Respostas a perguntas (questões), verificação de código, disseminação de informações sobre si mesmo - todas essas são tarefas importantes de um projeto de código aberto.

Embora a quantidade de tempo gasto em tarefas não programáticas dependa do tamanho e da escala do seu projeto, você deve estar preparado para resolvê-las sozinho ou encontrar um assistente para isso.

Se você faz parte de uma empresa que lança um projeto de código aberto, verifique com antecedência se possui recursos internos para seu desenvolvimento. Designe um oficial de suporte pós-lançamento e determine como as tarefas serão distribuídas na comunidade.

Se você precisar de um orçamento ou equipe dedicada para avançar, operar e apoiar o projeto, discuta isso o mais rápido possível.
avatarQuando você inicia um projeto de código aberto, é importante que os processos de gerenciamento da organização levem em consideração a contribuição e os recursos da comunidade que se formou em torno do projeto. Não tenha medo de envolver pessoas de fora, mesmo em aspectos importantes, principalmente se estiverem ativamente envolvidas.
@captainsafia , "Che, você deseja abrir o código do projeto?"

Participação em projetos de outras pessoas


Se seu objetivo é entender como interagir com outras pessoas e como o código aberto funciona, considere participar de um projeto existente que você usa e adora. Sua participação pode ser simples, como erros de digitação e atualizações de documentação.

Se você não entender como começar a participar do projeto de outra pessoa, consulte nosso guia Como participar de um projeto de código aberto .

Iniciando seu próprio projeto de código aberto


Não há um momento perfeito para abrir a fonte do seu trabalho. Você pode abri-los no estágio da ideia, no processo de trabalho ou após vários anos de fechamento.

Em geral, você pode abrir o código-fonte quando se sentir confiante o suficiente para mostrar seu trabalho a estranhos e obter seu feedback.

Cada projeto, independentemente do estágio em que você decidiu abrir a fonte, deve ter a seguinte documentação:


Eles ajudarão você a transmitir suas expectativas, aceitar as alterações de outros participantes e proteger os direitos legítimos de todos os coautores, incluindo você. Isso aumenta muito a probabilidade de uma experiência positiva.

Se o seu projeto estiver em um github e você colocar esses arquivos na categoria raiz com os nomes recomendados, o github os reconhecerá e os exibirá automaticamente para seus leitores.

Escolha da licença


Uma licença de código-fonte aberto garante que outras pessoas possam usar, copiar, modificar e fazer alterações no seu projeto sem consequências. Também o protege de situações legais desagradáveis. Você deve habilitar a licença ao iniciar um projeto de código aberto.

O trabalho jurídico não é fácil. Mas há boas notícias: você pode copiar uma licença existente e colocá-la em seu repositório, protegendo seu trabalho duro em um minuto.

MIT , Apache 2.0 e GPLv3 são as licenças mais populares, mas existem outras opções para você escolher.

Ao criar um novo projeto no Github, você pode escolher várias licenças. Ao escolher uma licença de código aberto, você abrirá seu projeto.

Escolha uma licença

Se você tiver outras dúvidas ou preocupações sobre os aspectos legais do código aberto, nós os descrevemos aqui .

Compilação de README


O arquivo LEIA-ME ("leia-me") não apenas explica como usar seu projeto, mas também explica por que é importante e o que os usuários podem fazer com ele.

Tente responder às seguintes perguntas no README:

  • O que esse projeto faz?
  • Como esse projeto é útil?
  • Como posso começar a trabalhar com ele?
  • Onde posso obter ajuda, se necessário?

Você pode especificar no README: como participar do seu projeto, quais são seus objetivos, falar sobre a licença e autoria. Se você não planeja aceitar as melhorias de outras pessoas, ou ele ainda não está pronto para a execução - basta escrever sobre isso.
avatarUma boa documentação significa mais usuários, menos pedidos de ajuda e mais colaboradores. (...) Lembre-se de que seus usuários não são você. Podem ser pessoas com experiência - muito diferentes das suas.
@tracymakes , "Escreva para que suas palavras sejam lidas (vídeo)"

Às vezes, as pessoas adiam a escrita do README porque sentem que o projeto não foi concluído ou não querem aceitar as melhorias de outras pessoas. Mas esta é apenas uma boa razão para escrever sobre isso.

Para inspiração, você pode ler o guia "Make README" ou o modelo README .

Quando você adiciona o arquivo README ao diretório raiz do projeto, o github o exibe automaticamente na página principal do repositório.

Escrevendo um guia para os participantes


O arquivo CONTRIBUTING informa ao seu público como se tornar um membro do seu projeto. Por exemplo:


Além dos detalhes técnicos, o arquivo CONTRIBUTING é um bom lugar para expressar suas expectativas em relação à participação de outras pessoas. Por exemplo:

  • Que tipo de participação você está esperando?
  • Seus planos e visão para o desenvolvimento do projeto
  • Como os participantes podem (e não podem) entrar em contato com você

Seu tom amistoso e amigável e propostas específicas de participação, como escrever documentação ou criar um site, podem ser de grande importância para atrair os recém-chegados a trabalhar em um projeto.

Por exemplo, o Active Admin inicia seu guia de participação com estas palavras:
Antes de tudo, queremos agradecer por você considerar participar do desenvolvimento do Active Admin. São pessoas como você que tornam o Active Admin uma ótima ferramenta.

Nos estágios iniciais de um projeto, seu arquivo CONTRIBUTING pode ser simples. Você sempre deve explicar como relatar erros e preencher perguntas, além de descrever os requisitos técnicos para editar membros (por exemplo, testes).

Com o tempo, você pode complementá-lo com respostas a perguntas frequentes. Por esse motivo, menos pessoas perguntam a mesma coisa repetidamente.

Para facilitar a compilação de um arquivo CONTRIBUTING, consulte o modelo de guia de colaboração da @ nayafia oumozilla's 'Como compilar o arquivo CONTRIBUTING.md' .

Link para o arquivo CONTRIBUTING dentro do README, para que mais pessoas o vejam. Se você colocar o arquivo CONTRIBUTING.md na raiz do seu projeto , o github fará referência automaticamente a ele quando alguém abrir uma nova pergunta (problema) ou adicionar uma edição ao projeto (solicitação de recebimento).

guia de colaboração

Desenvolvimento de um código de conduta


avatarTodos nós enfrentamos situações desagradáveis ​​quando o proprietário do projeto explicou algo rudemente ou os usuários fizeram perguntas básicas. (...) Um código de conduta se torna um documento fácil de consultar e que diz que sua equipe leva muito a sério um diálogo construtivo.
@mlynch , Tornando o código aberto um lugar mais feliz

Como resultado, o código de conduta define as regras básicas de conduta para os participantes do seu projeto. Isso é especialmente importante se você estiver lançando um projeto para uma empresa ou comunidade. Um código de conduta ajuda a estabelecer um comportamento saudável e construtivo na comunidade, o que reduz o estresse para você como a pessoa responsável pelo projeto.

Veja mais detalhes: Código de Conduta - Guia .

Além de descrever como você deseja que os participantes se comportem, o código de conduta também explica a quem e quando se aplica, e o que acontecerá se for violado.

Por analogia com a licença, você não precisa escrever o código sozinho, mas pode copiar uma das opções existentes. O contrato de membro é usado emMais de 40.000 projetos de código aberto, incluindo Kubernetes, Rails e Swift. Qualquer que seja o código usado, você deve estar preparado para aplicá-lo, se necessário.

Coloque o arquivo CODE_OF_CONDUCT.md na raiz do seu projeto, para que seja mais fácil encontrá-lo e vinculá-lo, por exemplo, a partir do README.

Nomeando e marcando seu projeto


A marca não é apenas um logotipo atraente e um nome memorável, mas também como você fala sobre seu projeto e sobre quem sua mensagem chega.

Escolhendo o nome certo


Escolha um nome que seja fácil de lembrar e, idealmente, dê uma idéia da essência do projeto. Por exemplo:


Se o seu projeto é uma adição a um projeto existente, use o nome dele como prefixo, isso ajudará a entender o que o seu projeto está fazendo. Por exemplo, node-fetch traz `window.fetch` para Node.js).

Opte pela clareza. Os trocadilhos podem ser divertidos, mas pense em pessoas de outras culturas ou com experiências diferentes das suas que talvez não entendam a piada. Seus usuários em potencial podem ser funcionários de empresas que conversarão com seus superiores sobre seu projeto. Não os faça corar ao mesmo tempo.

Conflito de nome


Verifique se há projetos de código aberto com o mesmo nome , especialmente se você usar o mesmo idioma ou ecossistema. Se seu nome corresponder a um projeto existente popular, você poderá confundir seu público.

Se você planeja iniciar um site, twitter ou qualquer plataforma de publicação, verifique se o nome que você precisa está gratuito lá. E é melhor reservar esses nomes agora para ter paz de espírito, mesmo se você ainda não planeja usá-los.

Certifique-se de não infringir a marca comercial de nenhuma empresa. No futuro, ela poderá solicitar que você feche o projeto ou até processe. Este é um risco injustificado.

Você pode verificar o conflito da marca no banco de dados global da marca WIPO. Se você estiver executando o projeto em nome da empresa, o departamento jurídico poderá ajudá-lo .

Por fim, faça uma pesquisa rápida no Google sobre o nome do seu projeto. As pessoas poderão encontrar facilmente seu projeto nele? Ou talvez algo indesejável apareça nesta solicitação?

A maneira como você escreve (e codifica) também afeta sua marca!


Ao longo da vida do projeto, você escreverá muito: README, guias, documentos da comunidade, respostas a perguntas, talvez até boletins e listas de discussão.

Seja uma documentação oficial ou uma mensagem regular, seu estilo de redação faz parte da marca do projeto. Pense na luz em que você olha para a platéia e se você escolheu o tom certo.
avatar , , . , , , , .
@janl, CouchDB, « Open Source»

Uma linguagem gentil e educada criará uma atmosfera agradável para novos participantes. Além disso, fique de olho na simplicidade da apresentação, pois para muitos leitores o inglês pode não ser nativo.

Não apenas as palavras que você escreve, mas também o estilo do código podem se tornar parte da marca do seu projeto. Angular e jQuery são dois projetos de amostra com estilos e recomendações rigorosos.

Não há necessidade de escrever um guia de estilo quando você está começando e, de qualquer forma, você provavelmente desejará incluir estilos diferentes no seu projeto. Mas você deve entender com antecedência que seu estilo de escrita e código atrairá algumas pessoas e afastará outras. Os estágios iniciais do projeto são uma oportunidade para criar um precedente a partir do qual o projeto crescerá da forma que você deseja.

Lista de verificação antes de iniciar


Você está pronto para abrir seu projeto? Aqui está uma lista de verificação para ajudá-lo. Quando você tiver verificado todos os itens, clique em "publicar" e se elogie.

Documentação


  • Há um arquivo LICENSE de código aberto no projeto
  • O projeto possui documentação básica (README, CONTRIBUTING, CODE_OF_CONDUCT)
  • O nome é fácil de lembrar, dá uma idéia da essência do projeto, não entra em conflito com os projetos existentes e não invade marcas comerciais.
  • A lista de problemas é atual, bem organizada e rotulada.

O código


  • O projeto usa convenções de código acordadas e nomes amigáveis ​​de funções / métodos / variáveis
  • O código é claramente comentado, intenções e casos especiais são documentados.
  • Em nenhum lugar há dados confidenciais, como senhas ou outras informações não públicas - no histórico de revisões, problemas (problemas) e solicitações de revisões (solicitações pull).

Pessoas


Se você é um indivíduo particular:

  • Você conversou com o departamento jurídico e / ou entendeu as regras de propriedade intelectual da sua empresa e as políticas de código aberto (se estiver empregado em algum lugar)

Se você é uma entidade legal:

  • Você falou com o departamento jurídico
  • Você tem um plano de marketing para lançar e promover um projeto?
  • Alguém foi designado responsável por interagir com a comunidade: responder perguntas, verificar solicitações de recebimento e anexá-las ao projeto
  • Pelo menos duas pessoas têm acesso administrativo ao projeto.

Você fez isso!


Parabéns por abrir o código fonte do seu primeiro projeto! Independentemente do resultado, trabalhar à vista das pessoas é um presente para a comunidade. Cada solicitação de confirmação, comentário e revisão é uma oportunidade de aprender e crescer para você e outras pessoas.

More articles:


All Articles