Como podemos automatizar coisas e facilitar o processo?

[ErickPetru]

Inspirado por indagações em https://github.com/vuejs-br/br.vuejs.org/issues/283, temos que refletir/decidir algumas coisas:

• [x] 1. Automatizar a criação de issues para itens ainda não traduzidos, talvez com um bot varrendo todos os .md dentro de src, mas levando em conta as issues já criadas manualmente para não gerar duplicações... Seria a melhor abordagem?
• [x] 2. Este repositório (assim como seu upstream) é um projeto completamente novo em VuePress (a documentação antiga era em Hexo). Diversas diferenças estruturais à parte, ambos são baseados em Markdown. Então, na teoria, poderíamos aproveitar traduções anteriores. Mas... O próprio core team falou para as equipes de tradução tomarem cuidado, pois há muitas diferenças (às vezes apenas em alguns parágrafos dentro de um arquivo que parece ser idêntico a um antigo). Como fazer isso de forma automática? Alguma ideia git diff poderia ajudar?
• [x] 3. Como vamos lidar com o deploy lá na frente? Nosso subdomínio br.vuejs.org está integrado com Netlify ao repositório vuejs-br/br.vuejs.org. No futuro, quando terminarmos o trabalho, poderemos arquivar o repositório antigo e tornar este o principal (talvez renomeando)... Ou mover este para lá como um novo branch e depois renomear os branches lá... De qualquer forma, não será muito complicado pois o core team pretende manter o Netlify, incluindo os subdomínios já mapeados como o nosso. Mas precisaremos definir como esta migração ocorrerá. E em que momento.
• [x] 4. Mais urgente agora: como vamos lidar com o deploy durante a tradução? É muito legal poder acompanhar um alpha, depois um beta, depois um RC de nosso trabalho de tradução. Vamos manter cada contribuidor testando só localmente? Ou vamos subir este repositório em um domínio temporário (talvez do Netlify mesmo) para acompanhar o andamento "ao vivo"?
• [x] 5. Aproveitando ou não trechos da tradução anterior, tem uma porrada de arquivos para serem traduzidos/revisados. É quase todo o trabalho de anos atrás acontecendo novamente! Apesar de cansativo, acreditamos fortemente que a documentação em português é um dos fatores que tornaram nosso querido framework tão bem visto no Brasil (e isto, claro, se reflete em mais vagas de emprego, mais visibilidade em eventos, etc). Como vamos instigar mais desenvolvedores brasileiros a colaborarem com este novo processo de tradução, para podermos entregar tudo o mais rápido possível e nos aproximarmos de comunidades como a chinesa, a francesa e a russa, que possuem documentação quase sempre sincronizada com a principal?

Vamos trocar ideias nesta issue para definir tais questões e eventualmente levantar outras.

[lpj145]

Já andei lendo parte da doc, alguns diff serão bem imenso, vale mesmo apena ficar pegando detalhes dessas diff ? é legal cada um assumir uma parte da doc, pra gente não ficar traduzindo a mesma coisa, alguém vai assumir um papel de redator ?

[GuiDevloper]

1: Já até tinha gerado uma lista das issues restantes, mas ainda ficaria manual :sweat_smile: Realmente, meu sonho sempre foi um bot que notifica caso upstream tenha commit novo. Agora entra esse caso interessante do Coverage da tradução, qual ainda não vi em outro lugar. Estudarei como seria essa implementação.

2: Para quem for contribuir recomendaria os seguintes passos:

1. Pegar arquivo deste repo
2. Fazer diff copiando conteúdo do arquivo da doc v2 original
3. Analisar se houve mudança dando prioridade à este repo
4. Traduzir mudanças usando como apoio o conteúdo antigo da doc v2 BR

4: Acho que o preview de deploy do Netlify salva bastante nisso, precisaríamos decidir qual será nosso domínio beta, será que a equipe lá teria alguma ideia de uso do subdomínio, ou será que daria pra criar um br.vuejs.org/v3?

[GuiDevloper]

Olá @lpj145, acredito que o diff funcionaria bem nos passos que ilustrei acima, é um trabalho de importante atenção aos detalhes mesmo e que pode ser feito com calma ao assumir uma issue/arquivo por vez, assim a responsabilidade de cada se mostra organizada.

[lpj145]

As issues deveriam fazer uma menção mais automatizada do arquivo em questão, ou estou vendo errado ?

[lpj145]

Diga-se de passagem, que é um dos melhores jeitos de aprender um framework, traduzindo a doc.

[ErickPetru]

1. Legal @GuiDevloper, se conseguir pensar nessa implementação para automatizar as issues, ainda mais considerando mudanças no upstream, será maravilhoso. Fico no aguardo sobre isso então, para poder fechar o item 1 desta issue.

2. Sobre o processo questionado pelo @lpj145 e abordado nesta questão de diff, acho que é bem por aí mesmo. Então, mesclando com o processo que tínhamos anteriormente com este. Se não esqueci nada neste processo, amanhã atualizo nosso README para deixá-lo registrado lá. Seria assim:

• Contribuidor faz fork deste repositório aqui;
• Avisa na issue correspondente em qual arquivo está trabalhando;
• Pega o arquivo correspondente (quando existir) na documentação v2 em inglês e tenta colar por cima do arquivo novo em inglês do seu fork realizado. Se não houverem trechos equivalentes, simplesmente traduz o arquivo;
• Usando o git diff, se houverem seções (às vezes vários parágrafos inteiros) que não mudaram de uma versão para outra, pode acessar a tradução da v2 e aproveitar os mesmos trechos. Senão, simplesmente traduz cada trecho necessário;
• Acabou de traduzir o arquivo; faz pull request contendo as alterações (atenção: o core team exige que todos os pull requests que subirão para upstream sejam descritos em inglês);
• Se algo der errado, demorar muito para traduzir ou sentir que não vai mais conseguir ajudar, avise na issue aberta para outra pessoa prosseguir;
• Se tudo der certo, parabéns e parte para o próximo.

3. Acho que arquivar o outro repositório e renomear este aqui quando estivermos prontos para lançar vai ser a opção mais simples. Se ninguém enxergar problemas nisso até lá, damos por encerrado este item.

4. Vou configurar este repositório no Netlify e poderemos utilizar a URL temporária do próprio serviço durante o processo de tradução. Utilizaremos nosso subdomínio somente quando formos lançar a documentação atualizada.

5. Não que este item esteja totalmente resolvido, mas fiz uma pequena divulgação em canais da comunidade Vue.js Basil e em minhas redes sociais. Acho que algumas pessoas serão atraídas para ajudar e, quem sabe, ajudarão a espalhar para outros potenciais contribuidores. Importante aproveitarmos a Hacktoberfest também.

[lpj145]

Concordo, fiz uma tradução do README para quem ta entrando, vou ajudar sim, quanto a issues, porque não teríamos uma issue o ai quem fosse trabalhar nela, faz o assing ? ou pede e vocês fazem o assing ? com relação ao pull, não ficou claro qual seria a estrutura do mesmo, acho que é legal, pra não ficar tudo zoado, entendeu ? melhor, até um exemplo.

[GuiDevloper]

Interessante deixar aqui registrado, alguns processos podem ser mantidos da tradução da v2, como o ciclo de avisar em issue/criar PR padronizada ilustrado no primeiro comment da br.vuejs.org#286 e seu PR especifico.

[rafaelmaiach]

Olá pessoal, muito bacana a discussão já levantada. Gostaria de fazer parte das traduções porém, é minha primeira experiência com open source num projeto grande como esse.

Esse contributor guideline que o @ErickPetru vai adicionar, já me deu uma boa noção de como começar.

Sobre os pontos citados:

1) Automatizar issues acho super válida. Poderíamos utilizar alguma padronização de título / labels ou algo que ajude a identificar no github as issues de tradução e, dependendo de quando (caso funcione), esse bot ficasse pronto, daria pra fazer uma limpeza manual (ou ajuste) nas issues que foram criadas manualmente. Acho que da menos trabalho isso, do que criar todas as issues que são necessárias.

4) Sobre o deploy, gosto bastante de como o netlify gerencia URLs, não vejo problema em termos uma URL beta, usando um dominio do proprio netlify (a não ser que o core team prefira que trabalhemos de outra forma)

5) Vim pela sua divulgação @ErickPetru, se quiser, posso ajudar com isso também dentro da minha rede.

Uma coisa que não me ficou muito claro:

1) As traduções já receberam o aval pra começar? Vi que já tem algumas issues abertas. 2) Vocês possuem alguma comunidade (discord por exemplo), com um canal focado nas traduções? De modo à ter um local mais centralizado para conversas mais casuais / dúvidas / etc?

[ErickPetru]

A todos os interessados em colaborar e que chegaram diretamente nesta issue: acabamos de publicar a versão traduzida e estendida do arquivo https://github.com/vuejs-br/docs-next/blob/master/src/guide/contributing/translations.md. Lá estão instruções detalhadas sobre como contribuir e quais padrões seguimos neste projeto. Em breve atualizaremos o README para facilitar a localização deste conteúdo.

[lpj145]

@ErickPetru é ideal eleger talvez a staff responsável pela validação e review dos pr ? porque tipo, talvez se a galera animar, vai aparecer seilá 10 15 pessoas pra ajudar... ai se o review demorar, vai ser um pouco dolorido, concorda ?

[ErickPetru]

@lpj145 não temos eleição, temos o convite para contribuição como mantenedor do repositório após sucessivas contribuições relevantes (e sem muitos problemas na revisão) por parte do colaborador. O último convidado foi @GuiDevloper ainda durante os trabalhos na documentação anterior, após uma grande reformulação da documentação pós Vue 2.5. Certamente teremos outros convidados saindo deste trabalho por aqui, já que bastante gente está aparecendo para contribuir.

[ErickPetru]

@GuiDevloper consegui resolver o problema do deploy e já atualizei o repositório e o README considerando nosso endereço temporário durante o período de tradução (https://vuejsbr-docs-next.netlify.app/). Lá na frente, só precisaremos trocar os arquivos que estiverem apontando diretamente para este endereço (na verdade, acho que só será o README mesmo). Isto fecha quase todos os pontos levantados aqui nessa issue.

Assim que dermos o bot como finalizado, fechamos tudo aqui e encerramos o projeto de "Organização" da tradução, concorda?

[emanuelgsouza]

Fala! Gostaria de fazer uma sugestão de uma prática que foi adotada na Tradução do Eloquent JS. (Conferir do repositório)

Basicamente:

• Nós criaríamos uma ISSUE que centraliza todos os arquivos (aqui vai ser bastante arquivo, mas podemos ter uma ISSUE para cada seção (Guide, Cookbook, Examples);
• Essa ISSUE controlaria quem está traduzindo qual arquivo. Assim, se eu quero traduzir um arquivo de GUIDE, eu vou na ISSUE: Tradução Guide v3 (exemplo), e vejo se o arquivo que eu quero traduzir está disponível. Estando, eu comunico que eu quero traduzir e a partir daí sigo a convenção e boas práticas que já estão definidas.
• Tendo definido o tradutor, é criado uma ISSUE para a discussão do tradução do arquivo (já está sendo feito aqui).

O que acham?

Talvez o bot nos ajude a criar essas ISSUEs com os arquivos (para não criarmos manualmente).

[GuiDevloper]

Eita, onde compartilharam isso pra chegar até no @emanuelgsouza :sweat_smile:

Gosto da ideia de issues centralizadoras, imagino o bot gerando-as já linkando issues existentes. Vou ver até a possibilidade de um comando pra dar Assign do tradutor escolhido pra issue correspondente ou alguma ligação automágica assim envolvendo até marcação dos assignees de cada issue na issue centralizadora :)

Valeu pela contribuição, agora que to percebendo o poder de bots, sinto essas coisas mais claras.

[emanuelgsouza]

Essas ideias de automatizações são sensacionais, realmente ficaria ainda mais simples para os coordenadores do projeto.

[ErickPetru]

Fala @emanuelgsouza, promissora essa ideia. Mas realmente acho ruim se trabalharmos só nas issues por categoria, pois o assign que o próprio Github permite em cada issue ajuda bastante a controlar quem está fazendo o que (e o que não tem ninguém fazendo) só de olhar na lista geral de issues. Então acho que a ideia do @GuiDevloper faz mais sentido, ter as issues por categoria controlando um status mais "global" daquela seção, e ter as issues por tarefa para podermos atribuir cada pessoa e discutir questões específicas de cada tarefa.

Mas aí eu refleti agora aqui e pensei... Já que estamos criando Project por categoria (ok, só criei Guide até agora, mas prometo que farei o resto), a própria guia Project já serve como este acompanhamento geral, então não sei se uma issue geral ajuda...

O processo que adotamos aqui foi copiado (digo, serviu de inspiração) a partir da comunidade francesa. Eles são muito rápidos na tradução lá (talvez por ter muita gente na França dando atenção ao Vue, já que o Nuxt surgiu lá). O que você pensa sobre isso @GuiDevloper?

[GuiDevloper]

Bem lembrado dos Projects @ErickPetru. Assumo que até usando Trello e outros Kanban-style ainda não sei bem a rotina e limitações do Projects aqui.

Engraçado que vi que um Bot podia manipular Boards também, então é uma questão de conhecer limitações e decidir a preferência, que aí o que eu disse de gerar issue centralizadora passa pra Project centralizador :)

PS: Bonitinho o Project que já mostra Assignee e PR daquela tarefa

[emanuelgsouza]

@ErickPetru tranquilo. Não sabia da inspiração. A ideia então, seria ter um project para seção (Guide, Cookbook e afins)? Bem, é uma outra forma de lidar com o gerenciamento. Vou seguir acompanhando e vou começar a ajudar na tradução!

[ErickPetru]

Legal @GuiDevloper, pra mim então fechou assim, vê se o bot consegue criar board por seção (se ainda não existir, claro, já que a de Guide já temos criada) e automaticamente definir cada issue para seu Project correspondente. Fica a dica aí pra vocês também: com a própria issue aberta, além de fazer assign da pessoa responsável, dá para clicar abaixo do Project dela e mover rapidamente de "To do" para "In progress" sem nem precisar abrir os cards.

[ErickPetru]

@GuiDevloper não tô cobrando não, mas só para ter uma ideia se devo começar a criar manualmente os próximos commits ou não. Você acha que o bot pode entrar em utilização em breve?

[GuiDevloper]

Resolvi vários bugs e o bot teve uma boa evolução que pode ser vista na Issue Experimental no meu fork. Para o uso oficial falta ler uma doc, implementar manipulação de Project e fazer uns testes isolados disso :)

PS: depois dá uma olhada no IN @ErickPetru