Corrigir ou aposentar um caso publicado

Corrigir um caso publicado é parte normal de manter um caso no ar. Um nível da rubrica ficou confuso, um teste inicial é instável, a situação precisa de mais uma frase. O Fito tem um caminho para isso, e ele preserva a identidade do caso: quem já está trabalhando mantém a versão fixada, e quem chega agora recebe a correção.

O que decide o caminho não é o tamanho da mudança. É se a mudança toca as referências de conhecimento do caso.

Os dois caminhos

O que mudou	Caminho
Código inicial, redação, texto da rubrica, descrições, o quiz	Uma nova versão deste caso
Os componentes de conhecimento ou níveis de Bloom nos objetivos de aprendizagem, nos pré-requisitos ou na rubrica	Um caso novo, e este é aposentado

O segundo caminho existe porque o conjunto de referências congela assim que um caso é publicado. Veja O conjunto de referências.

Decida em qual caminho você está antes de começar a editar. Uma edição que muda referências, descoberta na hora de publicar, é trabalho jogado fora.

Obter o caso para editar

/fito-case-edit <case-id>

<case-id> é o <id> da URL /cases/<id> do caso. Acrescente --dir <target> para escolher onde ele cai; o padrão é ~/.fito/authoring/<case-id>.

Isso clona o seu próprio repositório — não um fork — e faz checkout de main, o ramo de desenvolvimento. Você não precisa estar logado para um caso publicado.

Depois ele lê para você o resumo de orientação: a versão publicada atual, a última descrição de mudança e um resumo da árvore .case/.

Dois avisos não param o comando:

A conta do gh não é dona do repositório do caso. Editar localmente está certo. Publicar precisa de acesso de escrita ao repositório, que alguém de uma organização pode muito bem ter.
A árvore .case/ clonada não lê limpa. Leve isso para o validador antes de editar.

Quatro coisas recusam o comando de cara: um caso em rascunho, um caso aposentado, um id desconhecido, e um diretório de destino que não está vazio. Ele nunca sobrescreve nada.

Edite em `main`

Toda edição acontece em main. Os refs publicados vX.Y.Z e case/solution-vX.Y.Z nunca são reescritos.

Ajuste o código e o contrato .case/, rode o validador até ficar limpo, e comite. Edições comitadas em main não perdem nada esperando.

Publicar a nova versão

Combine o novo número de versão. Ele precisa ser estritamente maior que o publicado. Um patch para uma correção e um minor para um aperfeiçoamento são padrões sensatos; o número é escolha sua.
Coloque essa versão nos três lugares, ou a publicação recusa:
- .case/manifest.yaml — version:
- .case/manifest.yaml — submission.target_branch: (o pull request de quem aprende mira o ramo congelado da versão)
- .case/solution.yaml — branch: case/solution-vX.Y.Z
Reconstrua o ramo exemplar desta versão: parta do ramo de solução da versão anterior e reaplique sobre o main atualizado. Isso é trabalho de código, feito fora do Fito.
Aprove a descrição da mudança — o que mudou e por quê, algumas frases. Ela é servida com o caso e mostrada no próximo checkout, e é escrita em .authoring/change-description.md. Revise também a descrição de vitrine se a correção muda o que quem aprende deve ler antes de se inscrever.
Comite tudo, e rode a publicação a partir do checkout:
```
/fito-publish-case
```
Ele detecta que este diretório é um caso já publicado e toma o caminho de atualização sozinho.

Quando a publicação da versão para

Nada é registrado até a chamada final dar certo, e a sua árvore local nunca é modificada, então todas estas são seguras de corrigir e rodar de novo.

O que você vê	O que significa	O que fazer
“The knowledge-reference set is frozen across versions, and this tree changes it”	A edição está no outro caminho	Reverta a mudança de referência se ela não era intencional — ou desenhe o caso sucessor e aposente este
“.case/manifest.yaml is stale for the new version”	`submission.target_branch` ainda nomeia a versão antiga	Ponha a nova versão, comite, rode de novo
“.case/solution.yaml is stale for the new version”	`branch:` ainda nomeia a versão antiga	Ponha a nova, construa o exemplar nela, comite, rode de novo
“manifest.version is still …” ou “must be strictly greater than the published …”	A versão não mudou, ou andou para trás	Suba os três campos, revalide, comite, rode de novo
“The local solution branch … does not exist”	O exemplar desta versão não foi construído	Reconstrua a partir do ramo de solução da versão anterior
Uma rejeição do servidor do Fito	Muitas vezes um teste de alcance que falhou	O envio de uma atualização precisa de acesso de escrita ao repositório do caso. Confira no GitHub e rode de novo

A parada por referência congelada itemiza exatamente o que foi acrescentado e o que foi removido. Leia essa lista antes de decidir — é ela que separa um erro de digitação de uma mudança real de escopo.

Depois que dá certo

Você recebe a versão anterior e a nova, a URL web, e um aviso de que quem já aprendia mantém as versões fixadas enquanto /fito-case-open <case-id> agora serve a nova.

O seu checkout também é atualizado: as tags novas e os refs origin/… ficam locais. Se esse último passo relatar um ⚠, a versão está publicada e só a atualização falhou — pegue os refs depois com git fetch origin --tags.

Aposentar um caso

Aposentar um caso é marcá-lo como depreciado. Um caso depreciado:

some do catálogo, então nenhuma pessoa nova o encontra;
continua sendo servido na própria URL /cases/<id>, com um aviso;
continua aceitando entregas de quem já tinha começado, então ninguém fica preso no meio do caso.

Esse último ponto é o que torna aposentar seguro. Você está fechando a porta, não esvaziando a sala.

O controle fica na página do próprio caso:

Abra o caso e entre como dono dele ou como administrador. Retire this case aparece acima da capa do caso. Mais ninguém vê um controle ali.
Clique em Retire this case. A confirmação diz o que a mudança custa e o que ela deixa em paz: o caso sai do catálogo e para de aparecer na descoberta, enquanto quem já trabalha nele mantém o checkout, as entregas e as avaliações.
Clique em Retire this case de novo para confirmar. O aviso de depreciação aparece na página, sem recarregar.

Um administrador pode aposentar qualquer caso. A pessoa dona é a conta que registrou o caso. Isso é fixado no registro e nunca é transferido, então, sem esse alcance, um caso sobreviveria ao acesso de quem o criou sem ninguém poder aposentá-lo. O administrador usa o mesmo controle, e a mesma regra guarda a escrita em si.

Não coloque status: deprecated no .case/manifest.yaml no lugar disso. O campo existe, e o validador vai até pedir um deprecated_reason ao lado dele — mas nada no servidor do Fito lê esse valor. A aposentadoria é um estado que o servidor guarda, não algo que o repositório declara. Editar o manifesto não muda nada além da sua própria árvore, e os refs vX.Y.Z publicados não podem ser reescritos de qualquer forma.

Três coisas recusam a escrita: um caso que não existe, uma conta que não é dona nem administradora, e um caso em rascunho ou já aposentado. A confirmação diz o motivo em palavras.

Trazer um caso aposentado de volta

Aposentar é reversível. Reinstaurar move o caso de depreciado de volta para publicado, e ele retorna a todas as leituras que o escondiam: o catálogo, a lista Used in cases de um componente de conhecimento, a recomendação Do these first de outro caso, e as checagens que /fito-case-open, /fito-case-edit e /fito-publish-case fazem antes de tocar num caso. As entregas, as inscrições, os votos de curadoria e os refs vX.Y.Z publicados ficam intactos, porque só o status muda.

O controle fica onde estava o de aposentar:

Abra o caso aposentado e entre como dono dele ou como administrador. Reinstate this case aparece acima da capa do caso.
Clique em Reinstate this case, leia a confirmação, e clique de novo. O aviso de depreciação some, sem recarregar.

As mesmas três recusam, com a última invertida: um caso que não está aposentado.

O que vem a seguir

Desenhar um caso — onde um caso sucessor começa.
Publicar um caso — a primeira publicação, para comparar.