Um arquivo CITATION.cff informa, em YAML legível por pessoas e máquinas, como um repositório de código deve ser citado. Na forma mínima, ele registra versão do padrão CFF, uma mensagem, título, autores e versão do software; pode acrescentar data de lançamento, DOI, URL, licença e uma citação preferencial, como o artigo que descreve o método. Coloque o arquivo com esse nome exato na raiz do repositório, valide a sintaxe e mantenha os dados sincronizados com cada release.
Quando o arquivo está na branch padrão, o GitHub reconhece CITATION.cff e exibe uma opção para citar o repositório, convertendo os metadados para formatos como APA e BibTeX. Essa conversão não verifica se autores, DOI ou versão são verdadeiros. O resultado será tão confiável quanto a ficha fornecida pelo projeto.
Reúna os metadados antes de escrever YAML
Defina qual objeto o arquivo representa. É um programa, um pacote, um conjunto de scripts de análise ou um repositório que acompanha um artigo? Registre título estável, autores responsáveis, ORCID, versão, data de release, repositório, DOI arquivado e licença. Se ainda não existe release, decida se o arquivo descreverá o estado atual ou se a publicação deve esperar por uma versão identificável.
A lista de autores não precisa copiar automaticamente todos os commits. A equipe deve definir crédito conforme as contribuições e políticas do projeto. Preserve nomes nos campos corretos, com given-names e family-names, e confirme cada ORCID. Para uma organização autora, use o campo apropriado para entidade em vez de inventar nome e sobrenome.
Confira também a relação entre software e artigo. O software pode ser o objeto principal a citar, enquanto o artigo apresenta fundamentos e validação; em alguns casos, ambos devem ser citados. O CFF permite indicar preferred-citation quando o projeto deseja destacar outro recurso. Isso não deve ocultar o software nem substituir a citação da versão usada no método.
Comece por um modelo mínimo e válido
O conteúdo abaixo é um exemplo fictício. Substitua todos os valores; não copie DOI nem ORCID inventados para um projeto real.
cff-version: 1.2.0
message: "Se você usar este software, cite-o conforme os dados abaixo."
title: "Analise de entrevistas do projeto exemplo"
authors:
- family-names: "Silva"
given-names: "Marina"
version: "1.0.0"
date-released: "2026-09-11"
repository-code: "https://github.com/exemplo/projeto"
Use aspas quando um valor possa ser interpretado de modo inesperado, principalmente versões e datas. YAML depende de indentação por espaços; tabulações e níveis incorretos podem tornar o arquivo inválido. O nome deve ser CITATION.cff, com maiúsculas e extensão correta, e ficar na raiz para que ferramentas o encontrem.
O guia do schema CFF descreve chaves válidas, obrigatoriedade e exemplos. Consulte a versão do schema indicada em cff-version; não misture campos de versões diferentes. Campos como abstract, keywords, license, doi, url, repository-code e identifiers só entram quando representam informações verificadas.
Acrescente DOI, ORCID e licença sem duplicar sentidos
Se o software possui DOI de uma versão arquivada, use esse identificador no registro correspondente. Não coloque DOI do artigo como DOI do software. Quando deseja recomendar o artigo, use preferred-citation com tipo e campos próprios. Um repositório geral pode ter URL mutável, enquanto o DOI conduz a um depósito preservado; registrar ambos explica desenvolvimento e citação.
ORCID identifica pessoas, não organizações. Use o endereço completo e confira se pertence ao autor. A licença deve coincidir com o arquivo LICENSE e com o release. Não aplique licença ao código se a equipe não possui autoridade sobre todos os componentes ou dependências copiadas. Dependências mantêm licenças próprias.
Uma expansão fictícia poderia incluir:
doi: "10.0000/exemplo.invalido"
license: "MIT"
authors:
- family-names: "Silva"
given-names: "Marina"
orcid: "https://orcid.org/0000-0000-0000-0000"
Os valores acima são marcadores deliberadamente inválidos. Em produção, abra o DOI, verifique o ORCID do autor e confirme o identificador SPDX da licença quando o schema o exigir. Evite comentários que contradigam os campos estruturados.
Use citação preferencial somente quando houver relação clara
preferred-citation pode apontar para artigo, livro, relatório, conjunto de dados ou outro recurso suportado. No caso de um artigo metodológico, informe tipo, título, autores, periódico, ano, volume, páginas e DOI conforme disponíveis. O GitHub usa esse bloco para apresentar a citação preferida, mas o software ainda mantém seus próprios metadados no nível principal.
Não use a preferência para direcionar crédito a publicação que não descreve o código. Se um pacote implementa vários artigos, documente a relação no README e avalie se a mensagem deve pedir citação do software e da referência metodológica pertinente. A decisão precisa ser compreensível para quem reutiliza apenas uma parte.
Valide sintaxe, conteúdo e apresentação no repositório
Passe o arquivo por um validador compatível com a versão CFF. Corrija campos desconhecidos, indentação, datas e tipos. Depois, confira conteúdo manualmente: grafia de nomes, ordem de autores, ORCID, título, versão, DOI, URL e licença. Validade de schema não detecta um DOI pertencente ao objeto errado.
Faça o commit na branch padrão e abra a página do repositório. Verifique se a opção de citação aparece e examine as saídas. Compare APA ou BibTeX com a ficha original. Se o sobrenome foi interpretado incorretamente ou a versão sumiu, corrija o campo em vez de editar apenas a citação gerada.
Teste ainda o arquivo fora da interface do GitHub. Faça uma cópia limpa do repositório, confirme que o CITATION.cff acompanha a versão marcada e verifique se o DOI resolve para o depósito correspondente. Esse ensaio revela um erro comum: a branch principal já contém metadados da próxima versão, enquanto a tag citada conserva dados antigos. Nesse caso, a referência produzida pela página atual não descreve necessariamente o material que outra pessoa executou.
Quando houver automação de releases, inclua a validação do CFF no mesmo fluxo que testa o pacote e gera os artefatos. A automação pode verificar schema, formato da data e coincidência da versão, mas a equipe ainda precisa revisar autoria, licença e relações de crédito. Assim, a checagem técnica funciona como barreira contra inconsistências simples sem transformar decisões acadêmicas em regras cegas.
Uma revisão prática segue cinco etapas:
- delimitar o software e a versão representados;
- confirmar autores, ORCID, título, release, licença, repositório e DOI;
- preencher o modelo conforme o schema vigente, sem campos inventados;
- validar YAML e CFF, publicar na raiz e conferir a renderização;
- atualizar o arquivo junto de cada release e arquivar a versão citável.
Mantenha o CFF sincronizado com releases e depósitos
O arquivo não deve permanecer em 1.0.0 quando o repositório lança 2.0.0. Inclua sua atualização no checklist de release. Se o DOI é atribuído depois do depósito, volte ao repositório de desenvolvimento, acrescente-o e registre a mudança. Preserve tags e releases para que a referência continue recuperável.
Também alinhe CITATION.cff, README, LICENSE, metadados do repositório e registro arquivado. Divergência entre autores ou versões cria dúvida sobre o objeto oficial. Uma pessoa externa deve conseguir sair da opção “Cite this repository”, abrir o identificador e encontrar exatamente o software descrito.
Antes de encerrar uma release, peça a alguém que não editou o arquivo para conferir a ficha como faria um reutilizador. Essa pessoa deve localizar a versão, distinguir o DOI do software do DOI do artigo, reconhecer quem recebe crédito e chegar ao código preservado sem depender de uma explicação oral. Compare ainda a citação apresentada pelo repositório com os metadados do depósito e com a referência incluída no manuscrito. Se cada lugar aponta para uma versão ou ordem de autoria diferente, interrompa a publicação e resolva a divergência na fonte apropriada. Essa leitura independente costuma encontrar ambiguidades que passam tanto pelo schema quanto por quem já conhece o projeto.
O valor do CFF está em transformar instruções dispersas em metadados reutilizáveis. Ele não substitui documentação, release nem depósito persistente, mas conecta esses elementos. Quando é validado e atualizado como parte da publicação, reduz erros de citação e dá crédito à versão que realmente sustentou a pesquisa.
