Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
133 lines (79 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

133 lines (79 loc) · 5.24 KB
Raw

Contribua

Contribuir é mais fácil do que parece! Existem duas maneiras de adicionar e editar conteúdo: uma rápida, diretamente pelo navegador, e outra para contribuições mais complexas, usando Git na sua máquina.

Método Principal

Editando Pelo Site do GitHub

Este é o jeito mais simples e rápido para corrigir erros, adicionar parágrafos ou até mesmo criar uma página de conteúdo inteira sem precisar instalar nada.

  1. Encontre a Página: Navegue pelo site até a página que você deseja editar.

  2. Ache o Botão de Edição: No final de cada página, há um botão: "Edite essa página no GitHub" que te leva diretamente para o arquivo correspondente no nosso repositório do GitHub. Clique nele!

  3. Clique no Ícone de Edição: Na página do arquivo no GitHub, procure e clique no ícone de lápis que diz "Fork this repository and edit the file" no canto superior direito.

  4. Faça suas Alterações: O GitHub abrirá um editor de texto no seu navegador. Edite ou adicione seu conteúdo usando a sintaxe Markdown.

  5. Proponha as Mudanças: Ao final da página, você encontrará a seção "Propose changes".

  • No primeiro campo, escreva um título curto e claro para sua alteração (ex: "Corrige erro de digitação em guia de Git").
  • No campo de descrição (opcional), dê mais detalhes se necessário.
  • Clique no botão verde "Propose changes".
  1. Abra o Pull Request: O GitHub irá te levar para uma nova página para revisar suas alterações. Apenas clique em "Create pull request".

Pronto! Sua sugestão de mudança foi enviada para nós. A equipe irá revisar e, se estiver tudo certo, integrar ao site.

Fluxo Alternativo

Contribuindo Localmente (via Git)

Este método é ideal para contribuições maiores, como adicionar múltiplos arquivos, novas imagens ou para quem já tem familiaridade com Git e prefere trabalhar em seu próprio editor de código.

  1. Fork e Clone
  • Fork: Crie uma cópia (fork) do repositório PUC Tutor para a sua conta do GitHub.
  • Clone: Baixe o seu fork para a sua máquina.
git clone https://github.com/SEU-USUARIO/puc-tutor.git
cd puc-tutor
  1. Crie uma Branch

Crie uma branch específica para a sua alteração.

git checkout -b feat/tutorial-de-python
  1. Faça suas Alterações

Crie e edite os arquivos localmente, seguindo as regras de estrutura de pastas e nomenclatura de arquivos descritas acima.

  1. Commit e Push

Adicione e salve suas alterações no Git, depois envie para o seu fork.

git add .
git commit -m "Adiciona tutorial sobre Python"
git push origin feat/tutorial-de-python
  1. Abra um Pull Request

Volte para a página do seu fork no GitHub e clique no botão para criar um Pull Request. Descreva sua contribuição e envie para revisão.

Nosso processo usa o fluxo padrão do GitHub (Fork & Pull Request). Siga estes passos para contribuir ao PUC Tutor.

Formato do Conteúdo

Para manter a simplicidade e a acessibilidade, todo o conteúdo textual do PUC Tutor é escrito em Markdown (.md). Essa, é uma linguagem de marcação leve e fácil de aprender que permite formatar texto de maneira bonita e bem estruturada.

Para trechos de código, utilize blocos de código formatados para garantir a coloração correta da sintaxe.

Exemplo:

## Trecho de Código em Java

```java
public class Main {
  public static void main(String[] args) {
    System.out.println("Bem-vindo ao PUC Tutor!");
  }
}
```

Se você ainda não está familiarizado com Markdown, não se preocupe! Aqui estão alguns recursos para te ajudar a começar:

Em casos mais complexos, recomendamos utilizar o código de outras páginas como referência.

Organizando Arquivos e Imagens

Para manter nosso projeto organizado, pedimos que siga estas regras ao adicionar novos conteúdos:

  1. Localização dos Arquivos de Conteúdo

Todos os artigos, tutoriais e guias devem ser criados dentro do diretório: public/content/.

Dentro de public/content/enciclopedia/, você tem liberdade para criar novas pastas para organizar os assuntos. Por exemplo, um artigo sobre Python poderia ficar em public/content/enciclopedia/Python/introducao-python.md.

  1. Nomenclatura dos Arquivos

Use o padrão kebab-case: tudo minúsculo, sem acentos ou caracteres especiais, com palavras separadas por hífen (-).

  • ✅ Correto: como-instalar-java.md, resumo-calculo-1.md
  • ❌ Incorreto: Como Instalar o Java.md, resumo_cálculo1.md

Isso é necessário porque o nome do arquivo estará presente na URL da página

  1. Imagens

Sempre que possível, utilize imagens no formato SVG, que são leves e escaláveis.

Todas as imagens devem ser colocadas no diretório: public/assets/images/.

Para inserir uma imagem no seu texto, use o caminho relativo a partir do seu arquivo .md. Por exemplo, de um arquivo dentro de public/content/enciclopedia, o caminho seria:

![Descrição da imagem](../../assets/images/nome-da-sua-imagem.svg)