---

22.17 Política de depreciação

Como qualquer projeto animado com um escopo amplo, o Guix muda o tempo todo e em todos os níveis. Como é extensível e programável pelo usuário, mudanças incompatíveis podem impactar diretamente os usuários e dificultar suas vidas. Portanto, é importante reduzir as mudanças incompatíveis visíveis ao usuário ao mínimo e, quando tais mudanças forem consideradas necessárias, comunicá-las claramente por meio de um período de depreciação para que todos possam se adaptar com o mínimo de problemas. Esta seção define os compromissos do projeto para uma depreciação suave e descreve procedimentos e mecanismos para honrá-los.

Há várias maneiras de usar Guix; como lidar com a descontinuação dependerá de cada caso de uso. Elas podem ser categorizadas aproximadamente assim:

• gerenciamento de pacotes exclusivamente através da linha de comando;
• gerenciamento avançado de pacotes usando as interfaces de manifesto e pacote;
• Gerenciamento de sistema e home, usando as interfaces operating-system e/ou home-environment juntamente com as interfaces de serviço;
• desenvolvimento ou utilização de ferramentas externas que utilizam interfaces de programação como os módulos (guix ...).

Esses casos de uso formam um espectro com vários graus de acoplamento — de “distante” a fortemente acoplado. Com base nesse insight, definimos as seguintes políticas de depreciação que consideramos adequadas para cada um desses níveis.

Command-line tools

Os subcomandos Guix devem ser pensados como permanecendo disponíveis “para sempre”. Uma vez que um subcomando Guix deve ser removido, ele deve ser descontinuado primeiro, e então permanecer disponível por pelo menos um ano após o primeiro lançamento que o descontinuou.

A descontinuação deve ser anunciada primeiro no manual e como uma entrada em etc/news.scm; comunicações adicionais, como uma postagem de blog explicando a justificativa, são bem-vindas. Meses antes da data de remoção programada, o comando deve imprimir um aviso explicando como migrar. Um exemplo disso é a substituição de guix environment por guix shell, iniciada em outubro de 2021⁵³.

Devido ao amplo impacto de tal mudança, recomendamos realizar uma pesquisa com usuários antes de implementar um plano.

Package name changes

Quando um nome de pacote muda, ele deve permanecer disponível sob seu nome antigo por pelo menos um ano. Por exemplo, go-ipfs foi renomeado para kubo após uma decisão tomada upstream; para comunicar a mudança de nome aos usuários, o módulo do pacote forneceu esta definição:

(define-public go-ipfs
  (deprecated-package "go-ipfs" kubo))

Dessa forma, alguém executando guix install go-ipfs ou similar verá um aviso de descontinuação mencionando o novo nome.

Package removal

Pacotes cujos desenvolvedores originais declararam que atingiram o “fim da vida útil” ou não são mantidos podem ser removidos; da mesma forma, pacotes que estão falhando na compilação por dois meses ou mais podem ser removidos.

Não há um mecanismo formal de descontinuação para este caso, a menos que exista uma substituição, caso em que o procedimento deprecated-package mencionado acima pode ser usado.

Se o pacote que está sendo removido for um “leaf” (nenhum outro pacote depende dele), ele poderá ser removido após um período de revisão de um mês do patch que o removeu (isso se aplica mesmo quando a remoção tem motivações adicionais, como problemas de segurança que afetam o pacote).

Se tiver muitos pacotes dependentes — como é o caso, por exemplo, com a versão Python 2 — a equipe relevante deve propor uma agenda de remoção de descontinuação e buscar consenso com outros empacotadores por pelo menos um mês. Também pode convidar feedback da comunidade de usuários mais ampla, por exemplo, por meio de uma pesquisa. A remoção de todos os pacotes impactados pode ser gradual, abrangendo vários meses, para acomodar todos os casos de uso.

Quando o pacote que está sendo removido é considerado popular, seja ou não uma folha, sua descontinuação deve ser anunciada como uma entrada em etc/news.scm.

Package upgrade

No caso de pacotes com muitos dependentes e/ou muitos usuários, uma atualização pode ser tratada como a remoção da versão anterior.

Exemplos incluem grandes atualizações de versões de implementações de linguagens de programação, como vimos acima com Python, e grandes atualizações de bibliotecas “grandes” como Qt ou GTK.

Serviços

Mudanças nos serviços para Guix Home e Guix System têm um impacto direto na configuração do usuário. Para um usuário, ajustar-se a mudanças de interface raramente é recompensador, e é por isso que qualquer mudança desse tipo deve ser claramente comunicada com antecedência por meio de avisos de descontinuação e documentação.

A renomeação de variáveis relacionadas a configuração de serviço, home ou sistema deve ser comunicada por pelo menos seis meses antes da remoção usando os mecanismos (guix deprecation). Por exemplo, a renomeação de murmur-configuration para mumble-server-configuration foi comunicada por meio de uma série de definições como esta:

(define-deprecated/public-alias
  murmur-configuration
  mumble-server-configuration)

Os procedimentos previstos para remoção podem ser definidos assim:

(define-deprecated (elogind-service #:key (config (elogind-configuration)))
  elogind-service-type
  (service elogind-service-type config))

Campos de registro, notavelmente campos de registros de configuração de serviço, devem seguir um período de depreciação similar. Isso geralmente é obtido por meio de ad hoc. Por exemplo, o campo hosts-file de operating-system foi depreciado pela adição de uma propriedade sanitized que emitiria um aviso:

(define-record-type* <operating-system>
  ;; …
  (hosts-file %operating-system-hosts-file         ;deprecated
              (default #f)
              (sanitize warn-hosts-file-field-deprecation)))

(define-deprecated (operating-system-hosts-file os)
  hosts-service-type
  (%operating-system-hosts-file os))

Ao descontinuar interfaces em operating-system, home-environment, (gnu services) ou qualquer serviço popular, a descontinuação deve vir com uma entrada em etc/news.scm.

Core interfaces

Interfaces de programação principais, em particular os módulos (guix ...), podem ser confiáveis por uma variedade de ferramentas e canais externos. Qualquer alteração incompatível deve ser formalmente descontinuada com define-deprecated, como mostrado acima, por pelo menos um ano antes da remoção. O manual deve documentar claramente a nova interface e, exceto em casos óbvios, explicar como migrar da antiga.

Como exemplo, o procedimento build-expression->derivation foi substituído por gexp->derivation e permaneceu disponível como um símbolo obsoleto:

(define-deprecated (build-expression->derivation store name exp
                                                 #:key …)
  gexp->derivation
  …)

Às vezes, bindings são movidos de um módulo para outro. Nesses casos, bindings devem ser reexportados do módulo original por pelo menos um ano.

Esta seção não cobre todas as situações possíveis, mas espera-se que permita que os usuários saibam o que esperar e que os desenvolvedores se mantenham fiéis ao seu espírito. Por favor, envie um e-mail para guix-devel@gnu.org para quaisquer perguntas.