Registar-se na forja git.spip.net
Para propor uma alteração em git.spip.net precisa:
- ler a carta de boas vindas do SPIP e, se concordar com ela;
- registar-se no fórum de discussão;
- requerer acesso à forja na páginade inscrição.
Regras dre contribuição
- Criar um ticket em https://git.spip.net/spip/spip/-/issues antes de enviar uma proposta (que chamamos de PR [1]).
- Criar uma cópia pessoal do repositório (um fork) e aí criar uma ramificação (um branch) contendo as alterações propostas. O branch deve ser nomeado issue_xxx onde xxx é o número do ticket associado.
- As mensagens dos commits do branch issue_xxx devem seguir a nomenclatura dos Commits Convencionais. O corpo da mensagem deve ser claro e explicativo: descrever o problema tratado e as evoluções ou correções realizadas. Adicionalmente, a série de commits deve ser linear (sem commits de fusão, ou merge).
- Uma vez o branch finalizado, fazer um pedido de fusão via interface da forja, clicando em "nouvelle demande de fusion" a partir do branch em questão. Certificar-se de que o PR não contenha conflitos. Se existirem conflitos, corrigí-los com a ajuda de
git rebaseegit force push. O pedido passará por revisão e testato pelos membros da equipa e só poderá ser fundido com pelo menos duas aprovações dos membros. - O branch issue_xxx pode ser excluído após a fusão.
Uma vez o branch fundido, a equipe dee manutenção se encarregará de incluir uma linha no ficheiro CHANGELOG,
As mesmas regras aplicam-se aos membros da equipa para quem recomenda-se sempre passar um PR antes de integrar código ao branch principal. No entanto, se o patch é realmente pequeno e a pessoa tem certeza de que não causará problemas, ela pode decidir enviá-la diretamente para o branch master desde que se responsabilize pelo seu acompanhamento. Estes membros podem criar o branch diretamente no repositório, sem fork.
Sobre os Commits Convencioinais e os ficheiros CHANGELOG
Ler as matérias:
- Redigir uma mensagem de commit
- Manter um CHANGELOG
Sobre a fusão de branch
Na comunidade SPIP (core e plugins) não usamos commits de fusão de branch. Preferimos, para ter um histórico mais linear, usar um rebase seguido de um avanço rápido (fast forward).
# Dentro do branch a fundir
$ git rebase master
# Troca para o branch principal
$ git switch master
$ git merge branch_a_fundir
Na interface de Gitea, selecionar "Rebaser puis avancer rapidement".
O mesmo vale para os pulls.
Opta-se assim pela configuração git globale a seguir:
$ git config --global pull.ff only
$ git config --global pull.rebase = true
$ git config --global merge.ff = true
Regra de cherry-pick
Em geral, num git cherry-pick, usar a opção -x.
Regras de apresentação e escrita
Consultar as regras de codificação.
Regras de programação
Refletir
Antes de programar uma nova funcionalidade, refletir...
- métodos e algoritmos usados para a implementação: leveza, desempenho, robustez (não hesite em fazer alguns cálculos grosseiros para validar as escolhas);
- adequação ao projeto: portabilidade, segurança, flexibilidade;
- implicações nas outras funcionalidades: alterações e adições a fazer nas funcionalidades existentes;
- lugar "natural" para esta funcionalidade no projeto: em termos de interface, de ficheiros...
Não negligenciar a factorização ou partilha do código (para as funções, especialmente nos ficheiros a incluir). Evite, tanto quanto possível, ficheiros incluídos contendo código fora de funções (salvo quando for algo "natural" e intencional).
Nomear
De modo geral, os nomes devem ser nem muito curtos, nem muito longos, e devem ser suficientemente explícitos. Esta regras é particularmente importante para as variáveis globais, que podem ser partilhadas entre diversos ficheiros e inúmeras funções. Para as variáveis locais (ou seja, dentro de uma função), a regra é mais flexível. Nomeadamente, pode-se usar variáveis de uma letra, por exemplo para obter expressões mais compacta. Note-se que em todas as linguagens de programação, um certo número de letras são tradicionalmente associadas a certos usos (exemplos: $i, $j para contadores de loops, $n para uma contagem, $t para um instante ou uma duração em segundos...). Não desviar-se dessas convenções permite entrar mais rapidamente no ritmo durante a leitura do código.
Testar
Após uma alteração importante, é aconselhável testá-la você mesmo, sem esperar que alguém o faça em seu lugar. No contexto do SPIP, isso quer dizer que o programa funciona corretamente em um certo número de alojamentos web e de configurações (por exemplo: diferentes versões de PHP, de MySQL, restrições maiores ou menores de direitos de acesso aos diretórios...); mas também que um certo número de situações comuns (especialmente no caso de uma interface gráfica) são tratadas corretamente.