17 KiB
Como trabalhar em Artigos Guia
Com a tua ajuda, nós podemos criar uma ferramenta de referência compreensiva que ajudará milhões de pessoas que estão a aprender código nos anos que aí vêm. 💛
Tu podes:
- Ajudar-nos criando e Editando Artigos Guia.
- Ajudar-nos revendo pull requests para Artigos Guia
Passos para Criar e Editar Artigos Guia
- 🍴 Fazer fork a este repositório
- 👀️ Seguir as guias de contribuição delineados mais abaixo.
- 🔧 Fazer algumas mudanças impressionantes!
- 📖 Ler este guia de estilo de melhores práticas.
- 👉 Fazer um pull request
- 🎉 Ter o teu pull request aprovado - sucesso!
Ou então apenas criar um issue - qualquer pedacinho de ajuda conta! 😊
Segue estas guias recomendadas do nosso Guia de Estilo para um Artigo Guia interessante e completo
Criar um Pull request (PR) para propor mudanças
Há duas maneiras para propor uma mudança num repositório, depois de editares ou adicionar um Artigo Guia:
- Usando o GitHub Web Interface no teu browser.
- Trabalhando na tua máquina pessoal (recomendado para pré-visualizar mudanças).
Usando o GitHub Web Interface no teu browser
Vê a demonstração em vídeo ou segue os passos abaixo:
[A FAZER] Atualizar a gravação do GIF.
-
Ir à pasta "pages" (localizada no
client/src/pages/guide) e encontrar o artigo que gostarias de escrever ou editar.Todos os stubs estarão num ficheiro index.md
-
Carrega o icon de lápis do Edit this file e faz as tuas mudanças ao ficheiro usando o GitHub-flavored Markdown.
Se o icon estiver acizentado e a dar o aviso "You must be on a branch to make or propose changes to this file", então está provavelmente na tree de outra pessoa. No topo esquerdo da página estará uma caixa drop down que dirá "Tree: #######". Carrega no drop down e muda o branch para "master". Agora o lápis deve estar clicável.
-
Faz scroll até ao fim do ecrã e adiciona uma mensagem de commit a explicar as tuas mudanças.
(Opcional): Nós recomendamos vivamente fazer uma mensagem de commit convencional. Isto é uma boa prática que verás em alguns dos repositórios Open Source mais populares. Como developer, isto encoraja-te a seguir práticas standard.
Alguns exemplos de mensagens de commit convencionais:
fix: update HTML guide article fix: update build scripts for Travis-CI feat: add article for JavaScript hoisting docs: update contributing guidelinesMantém-nas curtas, não mais que 50 caracteres. Podes sempre adicionar informação adicional na descrição da mensagem de commit.
Isto não leva tempo adicional comparado com uma mensagem não convencional como 'update file' ou 'add index.md'
Podes aprender mais sobre commits convencionais aqui.
-
Seleciona a opção de radio button para "Create a new branch for this commit and start a pull request" e clica em Propose file changes.
-
No próximo ecrã podes adicionar outros detalhes sobre o teu PR e depois clica em Create pull request.
Parabéns 🎉! Criaste um pull request.
Trabalhando na tua máquina pessoal (recomendado para pré-visualizar mudanças)
Não é obrigatório trabalhares na tua máquina pessoal, a não ser que queiras pré-visualizar as tuas edições ou trabalhar com UI fixes e melhorias. Também é recomendado caso encontres problemas de git como conflitos de merge, rebasing, etc.
Lê estas guias em Como configurar o freeCodeCamp localmente
Ter um PR aceite
Aqui estão algumas diretrizes que os reviewers seguem ao analizar PRs:
- tem uma descrição e título relevantes
- o PR respeita o guia de estilo
- nós seguimos dicas QA gerais em Directrizes de Moderador
- desde que um pull request melhore ou expanda o guia, nós aceitamo-lo mesmo que contenha linguagem imperfeita ou conteúdo parcial
- pull requests mais antigos são analizados primeiro
Labels
- content é para pull requests que modificam o conteúdo dos artigos no guia (adicionam um novo artigo ou atualizam um já existente)
- duplicate é para pull requests que têm o mesmo conteúdo que outro PR
- changes requested é para pull requests que precisam de mudanças antes de serem merged
- stale é para pull requests com uma label "changes requested" que não tem actividade após 2 semanas e será consequentemente fechado
- Um pull requests stale deve ser fechado.
- Aqui está um exemplo.
Conteúdo Contraditório/Duplicado
UM PR é considera um duplicate se faz mudanças ao mesmo artigo que outro PR.
Em geral, um reviewer irá:
- Ordenar PR por mais antigo
- Procurar PRs com conteúdo parecido
- Merge do mais antigo para o mais recente
É muito provável que existirão conflitos de merge com PRs duplicados.
Reviewers farão todos os esforços para resolver estes conflitos e combinar os PRs duplicados.
Pedir Mudanças
Se um pull requests não é perfeito, o revisor poderá:
- pedir mudanças ao contribuidor e adicionar a label changes requested
- resolver problemas menores e fazer um commit> no topo do PR
Travis CI Build
Todos os PRs devem passar a verificação do Travis CI antes de acontecer o merge.
Se um PR quebra o build (uma verificação Travis CI falha e mostra um "X" vermelho) existem três causas prováveis.
Precisas de resolver o provlema antes de podermos merge o teu PR:
- O teu PR cria um novo artigo e falta o ficheiro 'index.md' algures.
- Todas as pastas no
src/pagesprecisam de um ficheiroindex.md(e o nome tem de serindex.md). - Dois cenários prováveis sãoT
- deste algum outro nome ao ficheiro do novo artigo que não
index.md, ou - criaste uma nova pasta e uma outra sub-pasta e escreveste o artigo na sub-pasta mas esqueceste-te de pôr um ficheiro
index.mdna nova pasta
- deste algum outro nome ao ficheiro do novo artigo que não
- Todas as pastas no
- O teu PR cria uma nova pasta e o nome da pasta não está formatado corretamente.
- O nome da tua pasta deve ser todo em minúsculas e formatado em kebab-case (ex. my-new-folder).
- O artigo não tem um campo para o
titleno topo.- Por favor refere à secção do Title mais abaixo por baixo de Guia de Estilo para escrever artigos.
Quando fechamos pull requests
Nós fechamos PR
- se um PR mais antigo do mesmo artigo é merged e o teu PR não adicionar novo conteúdo
- se há zero/pouco esforço (ex.: copiar e colas de outra fonte como a Wikipédia)
- se há texto copiado de uma fonte com copyrighti - ver problema de citação
- se não respeita o Guia de Estilo para escrever artigos
- se não respeita o Academic Honesty policy
- se está parado (se a mudança é pedida e não há atividade durante duas semanas)
Também, se estiveres a trabalhar de um artigo "stub", as tuas mudanças devem ser substanciais o suficiente para substituir o texto stub.
Não aceitamos um PR que só adiciona links à secção de "Mais Informação:".
O repositório tem um script Normalise.js que adiciona atributos a links, mas também procura texto "This is a stub..." via um RegEx.
Se encontrado, vai reverter o artigo de volta para o texto stub genérico (e apagar as tuas mudanças).
Este é comportamento pretendido, visto que permite-nos atualizar todos os stubs se o template stub por alguma razão.
Encontrar Ajuda
Há uma comunidade de suporte de uma equipa inteira de contribuidores, com quem podes trocar ideias e pedir opiniões sobre a tua escrita.
Mantém-te ativo no chat room de contribuidores e faz muitas perguntas.
Passos para rever pull requests para Artigos Guia
Esta secção é direccionada a revisores deste repositório.
Squash e Merge
Nós usamos a opção Squash and merge quando merging o PR que mantém a commit history limpa.
Filtrar PRs
PR, Open, Oldest First, Travis CI Build successful, no one assigned, no comments
is:pr is:open sort:updated-asc status:success no:assignee comments:0
PR, Open, Oldest First, Does not have labels:
platform,enhancement,invalidorchanges requested
Templates
Podes criar os teus próprios templates na feature inserida no GitHub em Saved replies ou usar os mais abaixo.
Agradecimento
Em inglês:
Thank you for your contribution to the page! 👍
We're happy to accept these changes, and look forward to future contributions. 🎉
Em português:
Obrigado pela tua contribuição para a página! 👍
Estamos muito felizes em aceitar estas mudanças e esperamos ver mais tuas contibuições no futuro. 🎉
Agradecimento e parabenização
Para agradecer e encorajar a primeira contribuição de um utilizador.
Em inglês:
Hi @username. Congrats on your first pull request (PR)! 🎉
Thank you for your contribution to the page! 👍
We're happy to accept these changes, and look forward to future contributions. 📝
Em português:
Olá @username. Parabéns pelo teu primeiro pull request (PR)! 🎉
Obrigada pela tua contribuição para a página! 👍
Estamos muito felizes em aceitar estas mudanças e esperamos ver mais tuas contibuições no futuro. 📝
Erro de Build
Em inglês:
Hey @username
So I'd love to be able to merge your changes but it looks like there is an error with the Travis CI build. ⚠️
Once you resolve these issues, I will be able to review your PR and merge it. 😊
Em português:
```markdown
Olá @username
Adoraria juntar as tuas mudanças mas parece que há um erro com o Travis CI build. ⚠️
Assim que resolveres estes problemas, poderei rever o teu PR e juntar ao repositório. 😊
---
> Estás à vontade de referenciar o [Guia de Estilo para escrever artigos](https://github.com/freeCodeCamp/freeCodeCamp#article-title) para este repositório no que toca a formatar um artigo corretamente para que o teu Travis CI build seja aprovado. ✅
>
> Também é uma boa prática no GitHub escrever uma breve descrição das tuas mudanças quando crias um PR. 📝
Syncing Fork
Quando o PR não está atualizado quanto ao
masterbranch.
Em inglês:
Hey @username
So I'd love to be able to merge your changes but it looks like there is an error with the Travis CI build. ⚠️
```bash
Error: ENOTDIR: not a directory, open 'src/pages/java/data-abstraction/index.md'
```
This particular error was not actually caused by your file but was an old error caused by merging faulty code to the `master` branch. It has since been resolved.
To pass the build, you will have to sync the latest changes from the `master` branch of the `freeCodeCamp/freeCodeCamp` repo.
Using the command line, you can do this in three easy steps:
```bash
git remote add upstream git://github.com/freeCodeCamp/freeCodeCamp.git
git fetch upstream
git pull upstream master
```
If you're using a GUI, you can simply `Add a new remote...` and use the link `git://github.com/freeCodeCamp/freeCodeCamp.git` from above.
Once you sync your fork and pass the build, I will be able to review your PR and merge it. 😊
Em português:
``````markdown
Olá @username
Adoraria juntar as tuas mudanças mas parece que há um erro com o Travis CI build. ⚠️
```bash
Error: ENOTDIR: not a directory, open 'src/pages/java/data-abstraction/index.md'
```
Este erro em particular não foi causado pelo teu ficheiro mas foi um erro antigo causado pelo <i>merge</i> de código defeituoso ao `master` <i>branch</i>. Foi, desde então, resolvido.
Para ser aprovado, terás que sincronizar as mudanças mais recentes do `master` <i>branch</i> do repositório do `freeCodeCamp/freeCodeCamp`.
Usando a linha de comandos, podes fazer isto em três passos fáceis:
```bash
git remote add upstream git://github.com/freeCodeCamp/freeCodeCamp.git
git fetch upstream
git pull upstream master
```
Se estás a usar um GUI, podes simplesmente `Add a new remote...` e usar o link `git://github.com/freeCodeCamp/freeCodeCamp.git` de cima.
Assim que resolveres estes problemas, poderei rever o teu PR e juntar ao repositório. 😊
---
> Estás à vontade para referênciar o artigo de [Sincronizar um Fork](https://help.github.com/articles/syncing-a-fork/) do GitHub para mais informação em como manter o teu <i>fork</i> atualizado com o repositório principal. 🔄
>
> Também é uma boa prática no GitHub escrever uma breve descrição das tuas mudanças quando crias um PR. 📝
Conflictos de Merge
Quando o PR tem conflitos de merge que necessitam de ser resolvidos.¹
Em inglês:
Hey @username
So I'd love to be able to merge your changes but it looks like you have some merge conflicts. ⚠️
Once you resolve these conflicts, I will be able to review your PR and merge it. 😊
---
> If you're not familiar with the merge conflict process, feel free to look over GitHub's guide on ["Resolving a merge conflict"](https://help.github.com/articles/resolving-a-merge-conflict-on-github/). 🔍️
>
> Also, it's good practice on GitHub to write a brief description of your changes when creating a PR. 📝
Em português:
Olá @username
Adoraria juntar as tuas mudanças mas parece que tens algums conflitos de <i>merge</i>. ⚠️
Assim que resolveres estes problemas, poderei rever o teu PR e juntar ao repositório. 😊
---
> Se não estiveres familiar com o processo de conflito de <i>merge</i>, consulta o guia do GitHub quanto a ["Resolver um conflito de merge"](https://help.github.com/articles/resolving-a-merge-conflict-on-github/). 🔍️
>
> Também é uma boa prática no GitHub escrever uma breve descrição das tuas mudanças quando crias um PR. 📝
¹ Se é um utilizador a contribuir pela primeira vez tem um problema de merge os mantainers irão resolver o conflito por eles.
Duplicado
Quando um PR é repetitivo ou duplicado.
Em inglês:
Hey @username
It seems that similar changes have already been accepted earlier for this article you're editing, sorry about that. 😓
If you feel you have more to add, please feel free to open up a new PR.
Thanks again! 😊
> Hey @username
It seems that similar changes have already been accepted earlier for this article you're editing, sorry about that. 😓
If you feel you have more to add, please feel free to open up a new PR.
Thanks again! 😊
---
> If you have any questions, feel free to reach out through [Gitter](https://gitter.im/FreeCodeCamp/Contributors) or by commenting below. 💬
Em português:
Olá @username
Parece que mudanças semelhantes já foram aceites antes para este artigo que estás a editar, desculpa. 😓
Se achares que tens mais a adicionar, estás à vontade para abrir outro PR.
Obrigada mais uma vez! 😊
---
> Se tens alguma questão, contacta-nos através do [Gitter](https://gitter.im/FreeCodeCamp/Contributors) ou comentando abaixo. 💬
Fechar pull requests inválidos
Quando o PR é inválido.
Em inglês:
Hey @username
You haven't actually added any content so I will be invalid pull requests this PR and marking it as `invalid`. 😓️
Feel free to open another PR though! 👍
Em português:
Olá @username
Não adicionaste nenhum conteúdo portanto vou ter de invalidar este <i>pull request</i> e marcá-lo como `invalid`. 😓️
Estás à vontade para abrir outro PR! 👍