Afixando versões de plugins e temas para instalações antigas do Discourse (.discourse-compatibility)

[Discourse]

Contexto

Às vezes, temas/plugins precisam fazer alterações que são compatíveis apenas com a versão mais recente do Discourse. Nesses casos, versões mais antigas do Discourse podem ser instruídas a usar uma versão ‘fixada’ mais antiga do plugin.

Isso é feito usando um arquivo .discourse-compatibility na raiz de um repositório de tema/plugin. É um arquivo YAML onde as chaves especificam a versão principal do Discourse e os valores representam a versão associada do seu tema/plugin.

As versões principais do Discourse podem ser especificadas usando os operadores <= e <. <= é o padrão por razões históricas, mas geralmente faz mais sentido usar <.

Fixando a versão de um tema/plugin

Por exemplo, se o núcleo do Discourse fizer uma alteração durante 3.2.0.beta2-dev (encontrado em version.rb) e seu plugin/tema começar a depender dela, você adicionaria uma entrada ao arquivo .discourse-compatibility assim:

< 3.2.0.beta2-dev: abcde

onde abcde é uma referência ao hash do commit ‘legado’ do SEU PLUGIN que deve ser usado em versões mais antigas do Discourse.

Agora, qualquer pessoa que use uma versão mais antiga do Discourse (por exemplo, 3.2.0.beta1 ou 3.1.4) usará a versão abcde do seu tema/plugin. Qualquer pessoa com 3.2.0.beta2-dev ou superior continuará usando a versão mais recente.

Múltiplas Entradas

Com o tempo, você pode adicionar várias linhas ao arquivo .discourse-compatibility. O Discourse sempre escolherá a especificação ‘mais baixa’ que corresponda à versão principal atual do Discourse. A ordem das linhas no arquivo tecnicamente não importa, mas recomendamos colocar as entradas mais recentes no topo.

‘Backporting’ de alterações para versões antigas do Discourse

Vamos imaginar um arquivo .discourse-compatibility como este, com duas especificações de versão diferentes fixadas em commits específicos do plugin:

< 3.2.0.beta1-dev: commithashfordiscourse31
< 3.1.0.beta1-dev: commithashfordiscourse30

Se você precisar fazer ‘backport’ de uma alteração para o Discourse 3.1, você faria algo como:

1. Crie um branch a partir do commit antigo (git checkout -b meu_nome_do_branch commithashfordiscourse31)

2. Commite sua alteração e envie para o origin. Se você usa os recursos de proteção de branch do GitHub, pode querer proteger este branch contra exclusão acidental.

3. Atualize o arquivo .discourse-compatibility no branch principal para que ele aponte para seu novo commit no branch de suporte 3.1.

Exemplo do Mundo Real

Aqui está um arquivo .discourse-compatibility real do plugin discourse-solved. Note que, no momento da escrita, ele ainda usa a sintaxe ‘legada’ sem operadores < ou <= explícitos. Portanto, cada linha é automaticamente interpretada como <=.

.discourse-compatibility

---

Este documento é controlado por versão - sugira alterações no github.

[NateDhaliwal]

Se a versão for \u003c 3.5.0.beta8-dev, ela incluiria 3.5.0?

[david (David Taylor)]

N. 3.5.0 é considerado “maior” que a versão pré-lançamento “3.5.0.beta8-dev”.

Você sempre pode tentar comparações em um console ruby:

> Gem::Version.new("3.5.0") < Gem::Version.new("3.5.0.beta8-dev")
=> false

[NateDhaliwal]

Entendido. Obrigado pela explicação!