istio.io
1.0.0
| Site | Status |
|---|---|
| istio.io | |
| preliminar.istio.io | |
| archive.istio.io |
Este repositório contém o código -fonte para iStio.io e preliminary.istio.io.
Consulte o arquivo principal do ISTIO ReadMe para saber sobre o projeto geral do ISTIO e como entrar em contato conosco. Para saber como você pode contribuir para qualquer um dos componentes do ISTIO, consulte as diretrizes de contribuição do ISTIO.
Para aprender a editar e construir o conteúdo deste repo, consulte a criação e edição de páginas.
Istio mantém duas variações de seu site público.
Istio.io é o site principal, mostrando documentação para a versão atual do produto. istio.io/archive contém instantâneos da documentação para versões anteriores do produto. Isso é útil para os clientes que ainda usam esses lançamentos mais antigos.
preliminary.istio.io contém a documentação atualizada ativamente para a próxima versão do produto.
O usuário pode navegar trivialmente entre as diferentes variações do site usando o menu de engrenagens no canto superior direito de cada página. Ambos os sites estão hospedados no Netlify.
As alterações de documentação estão comprometidas principalmente com o ramo principal do iStio.io. As alterações comprometidas com esta filial são refletidas automaticamente na preliminar.istio.io.
O conteúdo do iStio.io é retirado da última ramificação de versão-xxx. A filial específica usada é determinada pela configuração do projeto ISTIO.IO NETLIFY.
A verificação das atualizações para a filial principal atualizará automaticamente preliminar.istio.io e só será refletida no ISTIO.io na próxima vez que for criada uma versão, o que pode ser várias semanas no futuro. Se você deseja que algumas alterações sejam refletidas imediatamente no ISTIO.io, você precisa verificar suas alterações no ramo principal e na filial de liberação atual (denominada release-1.7 release-<MAJOR>.<MINOR>
Esse processo pode ser resolvido automaticamente por nossa infraestrutura. Se você enviar um PR para a filial mestre e anotar o PR com o rótulo cherrypick/release-<MAJOR>.<MINOR>
Aqui estão as etapas necessárias para criar uma nova versão de documentação. Vamos supor que a versão atual do ISTIO seja 1.6 e você deseja introduzir 1.7 que esteve em desenvolvimento.
Run make prepare-1.7.0 , e é isso. Isso pegará os documentos de referência mais recentes da nova ramificação de origem do ISTIO na pasta de content/en/docs/reference .
Para uma execução a seco antes do lançamento oficial, o Run make release-1.7.0-dry-run , que só criará uma nova ramificação release-1.7-dry-run e não tocará em outras ramificações.
No dia do lançamento, Run make release-1.7.0 . Isso faz alvo alterar algumas variáveis no master e release-1.6 e criará uma nova release-1.7 para a nova versão.
Vá para o projeto Istio.io no Netlify e faça o seguinte:
Altere a filial que é construída da filial da versão anterior para a nova ramificação de liberação, neste caso, release-1.7 (ou release-1.7-dry-run conforme apropriado).
Selecione a opção para acionar uma reconstrução e reimplementação imediata.
Depois que a implantação for concluída, navegue Istio.io e verifique se tudo parece bom.
Vá para o mecanismo de pesquisa personalizado do Google e faça o seguinte:
Faça o download do arquivo de contexto ISTIO.IO CSE na guia Avançado.
Adicione um novo FacetItem na parte superior do arquivo que contém o número da versão da versão anterior. Nesse caso, isso seria V1.6 .
Carregue o arquivo de contexto CSE atualizado para o site.
Na seção de configuração, adicione um novo site que abrange o diretório de arquivos da versão anterior. Nesse caso, o URL do site seria istio.io/v1.6/* . Defina o rótulo deste site com o nome do item de faceta criado acima ( V1.6 neste caso).
Alguns dias antes da liberação do patch, os gerentes de liberação devem notificar o DOC WG de que a versão é construída e está iniciando o teste de qualificação de longa data. No momento, mova os testes de automação do DOC para usar a nova versão para verificar os passes de teste automatizados do DOC.
Para mudar para um novo lançamento (verifique se você está na filial de lançamento do patch):
RUN go get istio.io/istio@AXY && go mod tidy .
Crie um PR com o go.* Alterações.
Criar uma nova versão do patch envolve modificar alguns arquivos:
Edite data/args.yml e altere o campo full_version para "AXY" . Isso é necessário apenas para um patch da versão current .
Conclua a nota de versão para a versão editando o arquivo de markdown content/en/news/releases/AXx/announcing-AXY/index.md . É aqui que você descreve as mudanças na versão. Veja outros arquivos existentes, por exemplo, conteúdo e layout.
Run make update_ref_docs para obter os documentos de referência mais recentes. Normalmente, isso é necessário apenas para um patch da versão current . Se necessário em um lançamento anterior, consulte Atualizando um arquivo.
Se a versão arquivada em uma filial mais recente (por exemplo, release-1.7:archive/v1.6 ) precisar ser atualizada devido a alterações no ramo de liberação antiga ( release-1.6 neste caso), você poderá make build-old-archive-1.6.0 no ramo master , que reverterá release-1.6 e substituirá o Arquivo anterior no master . Se essa atualização precisar ser refletida no ISTIO.IO, o PR poderá ser escolhido na filial para a versão current .
Os fluxos de liberação que começam com release-1.6 contêm testes para o conteúdo do teste. Cada liberação testa em uma versão/comprometimento específico do ISTIO. Quando a equipe de liberação tiver uma compilação, 1.xy , pronta para seus testes de longa execução, eles devem vir à equipe do DOCS para fazer os testes para o lançamento, comece a correr contra a construção.
Existem dois tipos de construções, public e private . As construções normais de desenvolvimento e liberação são construídas a partir de nossos repositórios públicos e têm imagens em um repositório de acesso ao público e são considerados public . Construções Private são aquelas em que não podemos revelar muito antes do lançamento. Normalmente, é um aviso prévio de que uma versão acontecerá em duas semanas para o CVE. Como não podemos revelar nada antes do lançamento real, a fonte e as imagens construídas estão em repositórios privados. Como a fonte e as imagens são privadas, não podemos realmente nos mudar para eles até que sejam lançados publicamente e, portanto, não há testes antecipados do lançamento no Istio.io. A diferença para construções private é que as imagens contra as quais testam nunca foram criadas no repositório public do GCR.IO; portanto, nesse caso, usamos as imagens do docker.io. Pode -se perguntar por que nem sempre usamos as imagens de liberação do Docker.io. Como queremos testar as construções public antes de serem lançadas, as imagens ainda não existem no Docker.io.
Para construções públicas:
go get istio.io/istio@commit && go mod tidy .Para construções privadas (isso é feito após o lançamento da construção):
go get istio.io/[email protected] && go mod tidy .Para ambas as compilações, queremos verificar se o hub/tag está correto no makefile.core.mk (eles mudam dependendo do uso das compilações privadas ou públicas). Procure a seção semelhante a:
# If one needs to test before a docker.io build is available (using a public test build),
# the export HUB and TAG can be commented out, and the initial HUB un-commented
HUB ?= gcr.io/istio-testing
# export HUB ?= docker.io/istio
# export TAG ?= 1.7.3
Para construções públicas, o export HUB/TAG S não seria declarado e possui valores corretos. Para construções privadas, ou o ramo master , o hub não seria declarado.
Por fim, crie e envie um PR com as alterações e pode -se ver os resultados do teste no PR. Normalmente, o PR não se fundirá até que a liberação seja lançada (às vezes existem várias construções para uma versão).
Muitos documentos no site ISTIO demonstram recursos usando comandos que podem ou não continuar funcionando à medida que o ISTIO evolui de liberação para liberação. Para garantir que as instruções documentadas permaneçam atualizadas com o menor teste manual contínuo possível, criamos uma estrutura para automatizar o teste desses documentos.
Cada página no istio.io que pode ser testada inclui uma indicação PAGE TEST no título da página. Por exemplo:
Uma marca de seleção verde indica que um teste automatizado está disponível para a página. A página está atualizada e trabalhando conforme documentado.
Um X cinza, por outro lado, significa que ainda não há teste automatizado disponível para a página. Agradecemos se você quiser ajudar a criar um! Nosso objetivo é eventualmente ter um teste automatizado para cada documento testável publicado no site ISTIO.
Consulte os testes Readme para obter mais informações.
O site é traduzido em vários idiomas. A fonte da verdade é o conteúdo em inglês, enquanto outros idiomas são derivados e, portanto, tendem a ficar um pouco para trás. Cada idioma do site obtém seu próprio diretório de conteúdo totalmente independente e arquivo da tabela de tradução. Os idiomas são identificados usando seu código de idioma internacional de 2 letras. O conteúdo principal do site está localizado no content/<language code> (por exemplo content/en ), e a tabela de tradução é um arquivo TOML-format em i18n<language code>.toml (por exemplo i18n/en.toml ).
Introdução à tradução é bastante simples:
Crie uma cópia completa do content/en diretório para o seu idioma. Por exemplo, você copiaria content/en para content/fr se estivesse fazendo uma tradução em francês.
Atualize todos os links no seu novo diretório de conteúdo para apontar para o seu diretório de conteúdo, em vez do conteúdo em inglês. Por exemplo, se você estivesse fazendo uma tradução em francês, alteraria links como [a doc](/docs/a/b/c) para [a doc](/fr/docs/a/b/c) .
Remova todas as diretivas de aliases na frente de todas as páginas de conteúdo. Os aliases são usados ao mover uma página para um novo local, para que não sejam desejáveis para um novo conteúdo.
Crie uma cópia do arquivo i18n/en.toml para o seu idioma. Por exemplo, você copia i18n/en.toml para i18n/fr.toml se estivesse fazendo uma tradução em francês. Este arquivo contém o texto exibido pela infraestrutura do site para itens como menus e outro material padrão.
Edite o arquivo hugo.toml para listar seu novo idioma. Pesquise a entrada [languages] e apenas adicione uma nova entrada. Isso diz ao gerador de sites Hugo para processar seu conteúdo.
Edite os scripts/lint_site.sh e pesquise check_content . Adicione outra chamada para check_content para o seu novo diretório de conteúdo. Isso garante que as regras de linha se apliquem ao seu novo conteúdo.
Edite o arquivo src/ts/lang.ts e adicione seu novo idioma. Isso adicionará seu idioma ao botão de alternância do idioma disponível no preliminar.istio.io e o fará para que seu idioma seja suportado no menu de seleção de idiomas.
Obtenha um administrador do Istio Github para criar uma nova equipe de mantenedor para o seu idioma. Para o francês, isso seria WG - Docs Maintainers/French .
Edite os CODEOWNERS de arquivos e adicione entradas para o seu idioma para fornecer à nova equipe que você criou a propriedade sobre o arquivo de tabela de conteúdo e tradução traduzido.
Você pode confirmar todas essas alterações e começar a traduzir o conteúdo e o arquivo de tradução de maneira puramente incremental. Ao criar o site, você encontrará seu conteúdo em <url>/<language code> . Por exemplo, depois de verificar tudo, você poderá chegar ao seu conteúdo em https://preliminary.istio.io/fr se estivesse fazendo uma tradução em francês.
Depois que sua tradução estiver completa e você está pronto para publicá -lo no mundo, há algumas outras mudanças que você precisa fazer:
Edite os layouts/index.redir . Pesquise translated sites e adicione uma linha para o seu idioma. Isso fará com que os usuários que cheguem ao site pela primeira vez sejam redirecionados automaticamente para o conteúdo traduzido adequado para eles. Para o francês, isso seria:
/ /fr 302 Language=fr
Edite layouts/partials/headers.html . Pesquise o switch-lang e você encontrará as definições para o menu de seleção de idiomas. Adicione uma linha para o seu novo idioma.
E é isso.
Temos vários cheques para garantir que vários invariantes sejam mantidos para ajudar a qualidade geral do site. Por exemplo, não permitirmos verificar links quebrados e fazemos uma verificação orgânica. Há algumas coisas que são difíceis de verificar sistematicamente através da automação e, em vez disso, exigem um humano para revisar há algum tempo para garantir que tudo esteja indo bem.
É uma boa ideia percorrer esta lista antes de cada grande lançamento do site:
Certifique -se de que as referências aos repositórios do ISTIO no GitHub não sejam nomes de ramificação de código de hardcode. Pesquise todos os usos de /release-1 ou /master em todos os arquivos de marcação e substitua aqueles por {{{<Source_Branch_Name>}} em vez disso, que produz um nome de ramificação apropriado para a versão.
Revise o arquivo .spelling para palavras que não deveriam estar lá. Os nomes de tipo em particular tendem a surgir aqui. Os nomes do tipo não devem estar no dicionário e, em vez disso, devem ser mostrados com backticks . Remova as entradas do dicionário e corrija quaisquer erros de verificação de ortografia que emergirem.
Garanta capitalização adequada. Os títulos de documentos precisam ser totalmente capitalizados (por exemplo, "Este é um título válido"), enquanto os títulos da seção devem usar apenas a capitalização de letras (por exemplo, "Este é um título válido").
Certifique -se de que os blocos de texto pré -formatados que referenciam arquivos dos repositórios do iStio github usem a sintaxe @@ para produzir links para o conteúdo. Veja aqui o contexto.
