GitHub - Colaborar diretamente no repositório

A colaboração direta através do GitHub é prática se quiser corrigir páginas regularmente, criar novos ficheiros Markdown ou trabalhar com o cofre do CircusWiki num editor como o Obsidian.

Se quiser apenas contribuir com um jogo, um método, um PDF, um link ou uma correção, o caminho mais simples é geralmente o melhor:

Voltar a Contribuir

O que precisa¶

• Uma conta gratuita no GitHub: https://github.com/join
• Opcionalmente, GitHub Desktop: https://desktop.github.com/
• Um editor de texto para ficheiros Markdown, por exemplo, Obsidian, VS Code ou um editor simples

O GitHub Desktop não é obrigatório, mas é mais fácil para muitas pessoas do que a linha de comando.

Encontrar o repositório¶

O repositório público encontra-se aqui:

https://github.com/nica-ev/circuswiki

Lá estão os ficheiros Markdown reais, imagens, traduções e ferramentas a partir dos quais o website é construído.

Fluxo de trabalho em resumo¶

O processo típico é:

1. Fazer um fork do repositório no GitHub.
2. Clonar a sua cópia para o seu próprio computador.
3. Fazer alterações num novo branch.
4. Editar ficheiros ou criar novos ficheiros Markdown.
5. Fazer commit das alterações.
6. Carregar o branch para o GitHub.
7. Abrir um Pull Request para que a alteração possa ser revista e aceite.

Passo a passo com GitHub Desktop¶

1. Fazer um fork do repositório¶

Abra o repositório CircusWiki no GitHub:

https://github.com/nica-ev/circuswiki

Clique em Fork. Isto cria uma cópia própria do repositório na sua conta GitHub. Nesta cópia, pode trabalhar sem alterar diretamente o projeto principal.

2. Clonar o repositório¶

Abra o GitHub Desktop e selecione:

File -> Clone repository...

Selecione o seu fork de nica-ev/circuswiki e escolha uma pasta no seu computador.

Depois disto, terá uma cópia local dos ficheiros.

3. Criar um branch¶

É melhor criar um branch próprio para a sua alteração, por exemplo:

adicionar-descricao-jogo
corrigir-link
novo-metodo-equilibrismo

Um branch mantém o seu trabalho separado do estado principal. Isto facilita a revisão posterior.

4. Editar ficheiros¶

Os conteúdos públicos encontram-se principalmente nas pastas de idiomas em docs/:

docs/de/
docs/en/
docs/es/
docs/pl/
...
docs/img/

Todas as línguas são equivalentes. Não existe uma língua principal em que novos conteúdos devam ser criados fundamentalmente.

Se criar uma nova página original, coloque-a na pasta de idioma na qual o texto está escrito. Um texto original em espanhol, por exemplo, deve ir para docs/es/, um em alemão para docs/de/, um em inglês para docs/en/.

O "frontmatter" no início do ficheiro é importante. Deve ser reconhecível que a página é um original, por exemplo:

translation_status: original
translation_source_lang: es

translation_source_lang corresponde à língua do texto original. A partir deste original, as traduções podem ser geradas automaticamente em todas as línguas suportadas mais tarde.

Ao editar, preste atenção ao seguinte:

• Não apague o "frontmatter" no início do ficheiro.
• Para novas páginas originais, defina translation_status: original e a translation_source_lang apropriada.
• Mantenha os links existentes sempre que possível.
• Não publique dados privados, chaves de API ou notas internas.
• Use imagens apenas se os direitos de uso forem claros.
• Prefira fazer alterações pequenas e claras em vez de alterações mistas muito grandes.

5. Fazer commit das alterações¶

No GitHub Desktop, verá os seus ficheiros alterados na secção Changes.

Escreva um breve resumo, por exemplo:

Corrigir lista de materiais no jogo de movimento
Adicionar aviso de segurança para Beigoma
Adicionar nova descrição de jogo

Em seguida, clique em Commit to <branch-name>.

6. Carregar as alterações¶

Clique em Push origin para carregar o seu branch para o GitHub.

7. Abrir um Pull Request¶

O GitHub Desktop ou o GitHub no navegador oferecerão então a opção de criar um Pull Request.

Um Pull Request significa: você propõe a sua alteração para o repositório principal. A alteração será revista, comentada se necessário e depois aceite ou trabalhada posteriormente.

Fundamentos do Markdown¶

Markdown é um formato de texto simples. Os caracteres mais importantes são suficientes para a maioria das contribuições:

# Título grande
## Título de secção

Texto normal com **parte em negrito** e *parte em itálico*.

- Ponto de lista
- Outro ponto de lista

[Texto do link](https://www.example.com)

Se algo não estiver claro¶

Não é preciso dominar imediatamente a colaboração direta através do GitHub. Se abrir um Pull Request e algo ainda não estiver correto, isso pode ser esclarecido na revisão.

Se quiser apenas contribuir com conteúdo e o caminho técnico parecer demasiado complicado, utilize simplesmente o e-mail na página de Contribuição.