edit-spec-file

Skill: Editar Arquivo Spec

Propósito

Fazer alterações em arquivos spec do Bottlerocket RPM mantendo conformidade estrita com as convenções de estilo do projeto. Esta skill garante arquivos spec consistentes e de fácil manutenção em todos os pacotes kit.

Quando Usar

• Adicionar novos arquivos fonte, patches ou templates a um pacote
• Adicionar serviços systemd ou arquivos de configuração
• Criar novos subpacotes (incluindo variantes FIPS)
• Modificar seções de build ou install
• Qualquer modificação em um arquivo .spec em kits/*/packages/

Pré-requisitos

• Leia ./STYLE-GUIDE.md completamente antes de fazer alterações
• Identifique um pacote similar existente como padrão de referência

Procedimento

1. Leia o Guia de Estilo

OBRIGATÓRIO: Leia ./STYLE-GUIDE.md antes de fazer qualquer alteração.

O guia de estilo contém:

• Regras [DEVE] que são obrigatórias
• Regras [NÃO DEVE] que são proibidas
• Regras [DEVERIA] que são fortemente recomendadas

2. Encontre um Pacote de Referência

Identifique um ou mais pacotes existentes similares para usar como padrão:

# Para pacotes Go
ls kits/bottlerocket-core-kit/packages/*/nvidia-k8s-device-plugin.spec

# Para pacotes C com serviços systemd
ls kits/bottlerocket-core-kit/packages/chrony/chrony.spec

# Para pacotes com variantes FIPS
ls kits/bottlerocket-core-kit/packages/amazon-ssm-agent/amazon-ssm-agent.spec

3. Aplique Alterações Seguindo a Ordem das Seções

Arquivos spec possuem uma ordem estrita de seções:

1. Definições %global
2. Metadados do pacote (Name, Version, Release, Summary, License, URL)
3. Arquivos fonte (numerados por faixa: <100 misc, 1xx systemd, 2xx tmpfiles, 3xx udev, 4xx licenças)
4. Patches (numerados 1000+)
5. BuildRequires / Requires
6. %description
7. Definições de subpacotes (%package, %description)
8. %prep
9. %build
10. %install
11. Seções %files

4. Numeração de Arquivos Fonte

Siga as faixas estabelecidas. Use os pacotes de exemplo para orientação específica, além dos exemplos abaixo:

• Source0-Source99: Fontes principais e arquivos diversos
• Source100-Source199: Arquivos de unidade Systemd
• Source200-Source299: Configurações Tmpfiles
• Source300-Source399: Regras Udev
• Source400-Source499: Arquivos de licença

CRÍTICO: Ao remover fontes, deixe lacunas - NÃO renumere fontes existentes, a menos que estejam na mesma centena.

5. Instale Arquivos na Ordem das Fontes

Arquivos em %install devem ser instalados na mesma ordem em que suas declarações Source aparecem:

# Fontes declaradas como:
Source1: nvidia-k8s-device-plugin.service
Source2: nvidia-k8s-device-plugin-conf
Source3: nvidia-k8s-device-plugin-exec-start-conf

# Instale na mesma ordem:
install -p -m 0644 %{S:1} %{buildroot}%{_cross_unitdir}
install -D -m 0644 %{S:2} %{buildroot}%{_cross_templatedir}/nvidia-k8s-device-plugin-conf
install -D -m 0644 %{S:3} %{buildroot}%{_cross_templatedir}/nvidia-k8s-device-plugin-exec-start-conf

6. Use Macros Corretas

Sempre use macros de compilação cruzada:

• %{_cross_bindir} não /usr/bin
• %{_cross_unitdir} para unidades systemd
• %{_cross_templatedir} para templates
• %{_cross_factorydir}%{_cross_sysconfdir}/... para padrões de fábrica
• %{_cross_fips_bindir} para binários FIPS

7. Padrão de Subpacote FIPS

Ao adicionar binários que precisam de variantes FIPS:

%package bin
Summary: Binários do pacote
Provides: %{name}(binaries)
Requires: (%{_cross_os}image-feature(no-fips) and %{name})
Conflicts: (%{_cross_os}image-feature(fips) or %{name}-fips-bin)

%description bin
%{summary}.

%package fips-bin
Summary: Binários do pacote, edição FIPS
Provides: %{name}(binaries)
Requires: (%{_cross_os}image-feature(fips) and %{name})
Conflicts: (%{_cross_os}image-feature(no-fips) or %{name}-bin)

%description fips-bin
%{summary}.

8. Permissões de Arquivos

Use permissões consistentes:

• 0755 para executáveis
• 0644 para arquivos de configuração, templates, arquivos de serviço
• Use install -p para preservar timestamps
• Use install -D quando diretórios pai precisarem ser criados

Lista de Verificação de Validação

Antes de commitar, acione um subagente para verificar de forma independente, referindo-se a este documento e à 'Lista de Verificação de Validação':

• Arquivos fonte numerados nas faixas corretas
• Ordem de instalação corresponde à ordem de declaração Source
• Todos os caminhos usam macros %{_cross_*}
• Nenhum arquivo instalado em /etc ou /var (use padrão de fábrica)
• %{_cross_attribution_file} na seção %files principal
• Diretiva %license para arquivos de licença
• Diretiva %dir para diretórios pertencentes ao pacote
• Nenhum comando de depuração (ls -la, etc.)
• Nenhum comentário desnecessário
• Formatação consistente (sem espaços em branco à direita, indentação consistente)
• Formato Release: 1%{?dist} (sem ponto antes de %)

Como Commitar Alterações

Ao commitar alterações em arquivos spec, use -F com um arquivo para preservar quebras de linha nas mensagens de commit:

# Escreva a mensagem em um arquivo e depois faça o commit com -F
msg = """nome-do-pacote: resumo da alteração

Descrição detalhada do que mudou e por quê.

Signed-off-by: Nome <email>"""
write("create", "/tmp/commit-msg.txt", file_text=msg)
bash("git -c commit.gpgsign=false commit -F /tmp/commit-msg.txt")

NÃO use git commit -m com repr() ou strings escapadas - isso escreve \n literal em vez de quebras de linha.

Anti-Padrões Comuns

NÃO:

• Use Release: 1.%{?dist} (errado: tem ponto)
• Inclua prefixo ./ em caminhos de arquivo
• Adicione comentários que repitam operações óbvias
• Use %exclude como substituto para configuração de build adequada
• Renumere fontes ao remover itens
• Instale arquivos fora da ordem das fontes
• Use caminhos fixos em vez de macros
• Crie links simbólicos entre pacotes

Referência Rápida

Adicionando um Serviço Systemd

1. Adicione fonte na faixa 100: Source101: myservice.service
2. Instale em unitdir: install -p -m 0644 %{S:101} %{buildroot}%{_cross_unitdir}
3. Adicione em %files: %{_cross_unitdir}/myservice.service

Adicionando um Template

1. Adicione fonte: Source5: mytemplate-conf
2. Instale: install -D -m 0644 %{S:5} %{buildroot}%{_cross_templatedir}/mytemplate-conf
3. Adicione em %files: %{_cross_templatedir}/mytemplate-conf

Adicionando um Diretório Drop-in

1. Crie diretório: install -d %{buildroot}%{_cross_unitdir}/myservice.service.d
2. Adicione em %files: %dir %{_cross_unitdir}/myservice.service.d