istio.io
1.0.0
| 地点 | 地位 |
|---|---|
| istio.io | |
| preliminary.istio.io | |
| Archive.istio.io |
该存储库包含istio.io和preliminary.istio.io的源代码。
请参阅主要的ISTIO读数文件，以了解整体ISTIO项目以及如何与我们联系。要了解如何为任何ISTIO组件做出贡献，请参阅ISTIO贡献指南。
要了解如何编辑和构建此存储库的内容，请参考创建和编辑页面。
ISTIO维持其公共场所的两个变体。
istio.io是主要站点，显示了产品当前发布的文档。 istio.io/archive包含了产品先前版本的文档快照。这对于仍使用这些较旧版本的客户很有用。
preliminary.istio.io包含用于下一个产品版本的主动更新文档。
用户可以使用每页右上角的Gear菜单在网站的不同变化之间进行微不足道的导航。这两个站点均在Netlify上托管。
文档更改主要致力于istio.io的主分支。对该分支的更改会自动反映在proliminary.istio.io上。
istio.io的内容取自最新的Release-XXX分支。使用的特定分支由istio.io netlify项目的配置确定。
签入主分支的更新将自动更新preliminary.istio.io，并且只能在Istio.io上反映下一次发布版本时，将来可能是几个星期。如果您想在istio.io上立即反射一些更改，则需要检查对主分支和当前版本分支的更改（名为Release release-1.7 release-<MAJOR>.<MINOR> 。
我们的基础架构可以自动照顾此过程。如果您向主分支提交PR，并使用cherrypick/release-<MAJOR>.<MINOR>标签注释PR，则一旦将PR合并到主人中，它将合并到指定的发行分支中。
这是创建新文档版本所需的步骤。假设当前版本的ISTIO为1.6，您希望介绍正在开发的1.7。
运行make prepare-1.7.0 ，仅此而已。这将从新的ISTIO源分支中获取最新的参考文档，然后将其列入content/en/docs/reference夹中。
对于正式发行之前的干式运行，Run make release-1.7.0-dry-run ，它将仅创建新的分支机构release-1.7-dry-run ，而不会触摸任何其他分支。
发行当天，Run make release-1.7.0 。这使目标将更改master和release-1.6中的某些变量，并为新版本创建新的分支版本release-1.7 。
转到Netlify上的istio.io项目，并执行以下操作：
将构建的分支从上一个发行版的分支更改为新版本分支，在这种情况下， release-1.7 （或适当的release-1.7-dry-run ）。
选择触发即时重建和重新部署的选项。
部署完成后，浏览istio.io并确保一切看起来都不错。
转到Google自定义搜索引擎，并执行以下操作：
从“高级”选项卡下载istio.io cse上下文文件。
在包含上一个版本的版本编号的文件顶部添加一个新的FacetItem。在这种情况下，这将是V1.6 。
将更新的CSE上下文文件上传到网站。
在“设置”部分中，添加一个涵盖上一个版本的存档目录的新站点。在这种情况下，网站URL将是istio.io/v1.6/* 。将此网站的标签设置为上面创建的刻面项目的名称（在这种情况下为V1.6 ）。
补丁发布前几天，发布经理应通知Doc WG，并启动了该版本的长期运行资格测试。此时，将DOC自动化测试移动以使用新版本来验证自动化DOC测试通过。
要转到新版本（请确保您在补丁的版本分支中）：
运行go get istio.io/istio@AXY && go mod tidy 。
使用go.*更改。
创建新的补丁发布涉及修改一些文件：
编辑data/args.yml ，然后将full_version字段更改为"AXY" 。这仅是current版本的补丁。
通过编辑Markdown File content/en/news/releases/AXx/announcing-AXY/index.md来完成发行版的发行说明。这是您描述发行版的更改的地方。请查看其他现有文件，例如内容和布局。
运行make update_ref_docs获取最新的参考文档。通常，这仅是current版本的补丁。如果在较早的版本中需要，请参见更新档案。
如果由于旧版本分支的更改（在这种情况下为release-1.7:archive/v1.6 release-1.6 ，您可以在Master Branch中运行make build-old-archive-1.6.0 ，在master Branch中，它将重新构建版本的release-1.6 ，并将其替换为master Branch的先前存档。如果此更新需要反映在istio.io中，则PR可以挑选到分支机构以进行current版本。
以release-1.6开头的发行流包含测试内容的测试。每个发布测试都针对特定的ISTIO版本/提交。当发布团队有一个构建， 1.xy ，准备长期运行的测试时，他们应该来到文档团队进行该版本运行的测试，以开始与构建有关。
public和private建筑有两种类型。正常的开发型和释放构建是由我们的公共存储库构建的，并在公共可访问的存储库中具有图像，并被视为public 。 Private版本是我们在发布前无法透露太多的私人版本。通常，这是一个提前通知，即CVE将在两周内发行。由于我们在实际发布之前无法透露任何内容，因此源和构建的图像是私人存储库。由于来源和图像是私人的，我们实际上不能搬到它们之前，直到它们公开发布，因此在istio.io中没有对版本进行早期测试。 private构建的区别在于，我们测试的图像从未在public gcr.io存储库中创建，因此在这种情况下，我们使用docker.io images。有人可能会问为什么我们不总是使用docker.io的释放图像。由于我们想在发布公共版本之前测试public构建，因此图像尚不存在Docker.io上。
对于公共建筑：
go get istio.io/istio@commit && go mod tidy 。对于私人构建（这是在发布构建后完成的）：
go get istio.io/[email protected] && go mod tidy 。对于这两种构建，我们都想验证Hub/Tag在makefile.core.mk中是否正确（它们会根据使用私人或公共构建而更改）。寻找类似的部分：
# 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
对于公共构建， export HUB/TAG S将不受调，并具有正确的值。对于私人构建或master分支，将不受调。
最后，创建并提交具有更改的PR，并且可以在PR中看到测试结果。通常，在发布发布之前，PR实际上不会合并（有时有多个版本以供发布）。
ISTIO网站上的许多文档都使用命令演示了功能，这些命令可能会随着ISTIO的发行演变而演变而来的命令。为了确保记录的说明保持最新的最新连续手动测试，我们创建了一个框架来自动化这些文档的测试。
可以测试的ISTIO.IO上的每个页面都包括页面标题下的PAGE TEST指示。例如：
绿色检查标记表明该页面可进行自动测试。该页面是最新的，并按照记录的方式工作。
另一方面，灰色X意味着该页面还没有可用的自动测试。如果您想帮助创建一个，我们将不胜感激！我们的目标是最终为ISTIO网站上发布的每个可测试文档进行自动测试。
有关更多信息，请参见测试读数。
该网站被翻译成多种语言。真理的来源是英语内容，而其他语言是派生的，因此倾向于稍微落后。每个站点语言都有自己的完全独立的内容目录和翻译表文件。使用其国际2字母语言代码来识别语言。主站点内容位于content/<language code> （例如content/en ）中，翻译表是i18n<language code>.toml （例如i18n/en.toml ）中的toml-format文件。
开始翻译非常简单：
为您的语言创建content/en目录的完整副本。例如，如果您正在进行法语翻译，则将content/en复制到content/fr 。
更新新内容目录中的所有链接，以指向您的内容目录，而不是指向英语内容。例如，如果您正在进行法语翻译，则将更改[a doc](/docs/a/b/c)等链接到[a doc](/fr/docs/a/b/c) 。
删除所有内容页面的前符号中的所有aliases指令。将页面移至新位置时，使用了别名，因此对于全新的内容而言，它们并不理想。
为您的语言创建i18n/en.toml文件的副本。例如，如果您正在进行法语翻译，则将i18n/en.toml复制到i18n/fr.toml 。该文件包含网站基础架构显示的文本，菜单和其他标准材料等内容。
编辑文件hugo.toml以列出您的新语言。搜索[languages]条目，只需添加一个新条目即可。这告诉Hugo网站生成器处理您的内容。
编辑文件scripts/lint_site.sh并搜索check_content 。将另一个呼叫添加到您的新内容目录中的check_content 。这样可以确保覆盖规则适用于您的新内容。
编辑文件src/ts/lang.ts并添加您的新语言。这将使您的语言添加到preliminary.istio.io上可用的语言切换按钮中，并将其添加到该语言选择菜单中。
获取一个iStio github管理员，为您的语言创建一个新的维护者团队。对于法国人来说，这将是WG - Docs Maintainers/French 。
编辑文件CODEOWNERS并为您的语言添加条目，以使您创建的新团队对翻译内容和翻译表文件的所有权。
然后，您可以提交所有这些更改，并且可以以纯粹的增量方式开始翻译内容和翻译文件。构建网站时，您将在<url>/<language code>上找到您的内容。例如，一旦您检查了所有内容，您就应该能够在https://preliminary.istio.io/fr上获取您的内容，如果您正在进行法语翻译。
一旦翻译完成并准备好将其发布给世界，您还需要进行其他一些更改：
编辑文件layouts/index.redir 。搜索translated sites并为您的语言添加一行。这将导致用户首次进入网站，自动将其重定向到适合他们的翻译内容。对于法语，这将是：
/ /fr 302 Language=fr
编辑文件layouts/partials/headers.html 。搜索switch-lang ，您会找到语言选择菜单的定义。为您的新语言添加一行。
就是这样。
我们进行了许多检查，以确保维护许多不变性，以帮助该网站的整体质量。例如，我们不允许检查折断的链接，并进行拼写检查。有些事情很难系统地检查自动化，而要求人类在一段时间内进行审查，以确保一切顺利。
在本网站的每个主要版本之前，最好浏览此列表是一个好主意：
确保对GitHub上的ISTIO存储库的引用不要硬码分支名称。搜索所有在所有标记文件中搜索/release-1或/master的用途，然后用{{<source_branch_name>}}}替换为{{<source_branch_name>}}}，该文件会产生适合版本的分支名称。
查看.spelling文件中的单词不应该在那里。特别是类型名称倾向于在此处爬行。类型名称不应在字典中，而应以backticks为单位显示。从字典中删除条目，并修复出现的任何拼写检查错误。
确保适当的资本化。文档标题需要充分资本化（例如“这是一个有效的标题”），而部分标题应仅使用首字母大写（例如“这是有效的标题”）。
确保从istio github存储库中引用文件的预制文本块使用@@语法来生成内容的链接。请参阅此处的上下文。
