Diretrizes de Contribuição
Welcome to the contribution guidelines for the frc-docs project. If you are unfamiliar to writing in the reStructuredText format, please read up on it here.
Importante
FIRST® retém todos os direitos de documentação e imagens fornecidas. O crédito dos artigos/atualizações estará no histórico de commits do GitHub.
Declaração de Missão
A Missão da WPILib é permitir que as equipes da FIRST Robotics se concentrem em escrever software específico para jogos ao invés de se concentrar em detalhes de hardware - «eleve o chão, não abaixe o teto». Trabalhamos para permitir que equipes com conhecimento de programação limitado e/ou com experiência de mentor tenham o maior sucesso possível, sem prejudicar as habilidades de equipes com capacidade de programação mais avançada. Oferecemos suporte aos componentes do sistema de controle do Kit of Parts diretamente na biblioteca. Nós também nos esforçamos para manter a paridade entre os principais recursos de cada linguagem (Java, C++ e LabVIEW da NI), para que as equipes não fiquem em desvantagem ao escolher uma linguagem de programação específica.
Esses documentos servem para fornecer um campo de aprendizagem para todas as equipes da FIRST Robotics Competition. As contribuições para o projeto devem seguir estes princípios básicos.
Documentação liderada pela comunidade. As fontes de documentação são hospedadas publicamente e a comunidade pode fazer contribuições
Documentação estruturada, bem formatada e limpa. A documentação deve ser limpa e fácil de ler, tanto do ponto de vista da fonte quanto o da versão lançada
Relevante. A documentação deve ser focada na FIRST Robotics Competition.
Por favor, veja o Guia de Estilo para informações sobre como estilizar sua documentação.
Processo de Lançamento
frc-docs usa um processo de lançamento especial para lidar com o site principal /stable/
e o site de desenvolvimento /latest/
. O fluxo desse processo é detalhado abaixo.
Durante a Temporada:
Commit é feito para o branch
main
Atualiza
/stable/
e/latest/
no site
Fim da Temporada:
Repositório é marcado com um ano, para propósitos de arquivamento
Off-Season:
branch
stable
é bloqueado no último commit feito ainda na temporadaCommit é feito para o branch
main
Apenas atualiza
/latest/
no site da documentação
Criando uma PR
PRs devem ser feitas em ao repositório frc-docs no GitHub. Elas devem ser feitas na branch main
e não na stable
.
Criando Conteúdo Novo
Obrigado por contribuir para o projeto frc-docs ! Existem algumas coisas que você deve saber antes de começar!
Onde colocar os artigos?
A localização de novos artigos pode ser um tema controverso. Artigos isolados que se encaixam bem em uma categoria devem ser colocados na respectiva categoria (documentação de algo sobre simulação deve ser colocado na seção de simulação). Porém, as coisas podem ficar complicadas quando um artigo combina ou faz referência a duas seções distintas. Nessa situação, recomendamos ao autor que abra um issue no repositório, para gerar uma discussão antes da abertura da PR.
Nota
Todos os novos artigos passarão por um processo de revisão antes de serem integrados ao repositório. Esse processo de revisão será feito por membros da equipe WPILib. Novos Artigos devem ser sobre software e hardware com suporte oficial FIRST. Documentação em bibliotecas ou sensores não oficiais não serão aceitos. Esse processo pode levar algum tempo para ser revisado, por favor seja paciente.
Onde colocar seções?
Seções podem ser bem complicadas, pois elas contem grandes quantidade de conteúdo. Recomendamos que o autor abra um issue para gerar uma discussão antes da abertura da PR
Referenciando Outros Artigos
No caso do artigo referenciar conteúdo que é descrito em outro artigo, o autor deve se esforçar para referenciar aquele artigo logo na primeira ocorrência.
Imagine que temos o seguinte conteúdo em um tutorial de drivetrain:
Teams may often need to test their robot code outside of a competition. :ref:`Simulation <link-to-simulation:simulation>` is a means to achieve this. Simulation offers teams a way to unit test and test their robot code without ever needing a robot.
Perceba como apenas a primeira ocorrência de simulação é referenciado. Essa é a estrutura que o autor deve seguir. Algumas vezes o artigo referenciado tem diferentes assuntos em seu conteúdo. Se você referenciar diferentes assuntos daquele artigo, você deve referenciar cada nova ocorrência apenas uma vez ( exceto em casos onde o autor considerar adequado o contrário).