管理项目网站
每个Apache项目或podling都有一个网站托管在apache.org网站
Apache提供了支持它的工具。每个项目都决定其网站的外观、内容、维护方式以及使用什么软件来支持它,只要结果是我们的公共web服务器可以为浏览器提供静态文件。我们对.htaccess文件和CGI脚本的支持也很有限。
目录
规划项目网站
您的项目团队希望构建一个优秀的应用程序,以解决问题、简化流程或开创新局面。你还希望人们找到它,尝试它,并采用它。你的项目网站是吸引和吸引项目开发贡献者以及将成为你用户社区一部分的人员和组织的关键。
您的网站必须
该网站还应该
- 解释你的项目产品的作用。
- 宣传你的产品如何解决问题或创造新机会。
- 邀请人们参与开发团队。
- 提供一种简单的方法来下载您希望公众使用的产品的最新版本。
- 提供文档,帮助项目以外的人了解如何开始使用产品以及如何继续使用。
- 描述项目团队的工作方式及其与Apache Software Foundation的连接。
- 解释人们如何与项目联系以提供反馈或提出问题。
一旦你概述了网站上的内容,并决定了如何以及在哪里显示,你就需要决定如何构建网站。
创建网站
项目可以自由选择自己的网站样式和布局,并有一系列实际创建页面的选项。目标是创建一个信息丰富且有用的静止的HTML网站,可以吸引访问者,向他们解释您的项目,并提供下载链接和文档,以便他们可以使用您的项目应用程序。
JavaScript问题
许多TLP站点使用JavaScript(JS)提供从菜单导航到动画和图像库的功能。虽然JS可以提高大多数访问者的网站体验,但它也会带来问题:
- 禁用脚本语言的访问者一般感兴趣的网站可以有多达10%的网站访问者在浏览器中禁用JS;针对技术性更强的受众的网站,这一比例可能更低。即使访问者的浏览器禁用了脚本语言,也要确保您的站点能够访问它必须提供的基本信息。
- 使用辅助设备阅读和处理网页的访问者。在“JavaScript和辅助读者”上进行web搜索将提供有关编写和部署JS的有用信息,从而使使用辅助设备的用户访问项目网站的问题最少。这个辛西娅说该网站可以帮助您检查网站是否符合可访问性准则,包括JavaScript问题。
1.网站建设选项
鹈鹕
鹈鹕是用Python编写的静态站点生成器。亮点包括:
- 使用您选择的编辑器以reStructuredText或Markdown格式直接编写内容。
- 包括一个简单的CLI工具来(重新)生成您的站点。
- 易于与分布式版本控制系统和web挂钩接口。
- 完全静态输出很容易在任何地方托管。
鹈鹕有路可走从许多技术迁移现有网站,包括Blogger、Dotclear、Posterous、Tumblr、WordPress和RSS/Atom。
任何ASF项目都可以使用ASF-Pelican模板作为他们项目网站的基础。
查看如何使用鹈鹕和建筑机器人开发和部署项目网站。
Pelican支持平面网站和具有子目录的网站。对于后者,Pelican提供了插件.
浏览鹈鹕插件集合查找其他支持您要添加到站点中的功能的用户。
这个GitHub查询返回ASF存储库其中有鹈鹕
主题。你可以把它们作为鹈鹕队的例子来回顾。
杰基尔
杰基尔是一个使用Markdown开发博客或静态网站的简单工具,很容易将生成的网站部署为GitHub页面。网上有很多关于这样做的教程。
雨果
至少六个ASF项目使用雨果,一个用于构建静态网站的开源框架。
J贝克
至少两个ASF项目使用J贝克,一个基于Java的工具,用于构建静态网站。
MKDocs公司
MKDocs公司是一个用于创建项目文档的静态站点生成器。然而,至少有一个ASF项目使用它来构建整个项目网站。请参见这个便条用于保留项目站点的生成序列.asf.yaml文件文件。
Markdown中的基本网站模板
如果您想开始使用易于使用的,降价-基于许多项目使用过的网站,请参阅Apache项目网站示例存储库,它具有许多有用的功能和使用说明svnpubsub服务器
.
HTML文件
您可以使用任何其他生成静态HTML页面的工具,或手动编码这些页面。然后将它们签入项目的网站存储库。签入将触发站点更新。
使用.htaccess文件自定义网站指令
项目网站可以使用.htaccess文件来设置自定义重定向和其他对请求处理的调整。默认值允许覆盖设置为全部
,它通常支持任何类型的重定向或重写(使用重写规则
,重定向
等)。一些项目网站在其专用虚拟主机配置中具有自定义设置,这可能需要向基础结构团队寻求帮助。如果你有疑问,问问。
不支持的工具
GitHub页面
Infra没有适当的结构来支持使用GitHub页面用于项目网站。
阿帕奇CMS
Apache CMS自2010年起用于构建和部署其网站,截至2021年7月31日不再提供。所有使用它的项目,包括主要的Apache网站,都已经或必须转移到其他技术。那些逗留的人会发现,在某个时候,他们无法再更新自己的网站。请参阅下面站点管理工具部分中的注释。
2.网站存储库
如果您还没有项目的网站存储库,可以使用创建一个自助服务.
惯例是命名存储库$项目site.git
例如httpd-site.git网址
.
将启动构建所需的内容复制到新存储库的主分支中。这将作为构建过程的基础。
3.构建过程
配置Pelican或Jekyll以在其内容更改时自动构建站点,使用.asf.yaml文件和Buildbot。
4.登台网站
使用.asf.yaml文件使用Git存储库,一旦您将生成的网站提交并推送到分支机构,您就可以设置一个临时网站来测试您的更改,然后再将其发布到主网站。
为此,请添加或编辑.asf.yaml文件
在staging分支(生成生成输出的位置)中,添加以下内容(假设您的staging分行是asf-staging):
暂存:配置文件:~whoami:asf分期
提交到此分支后,您的暂存网站将显示最新输出,网址为:https://$项目.stage.apache.org/
有关更多详细信息,请参阅.asf.yaml文件.
5.出版
当您准备将Git网站存储库的分支发布到项目网站时,可以使用.asf.yaml文件
:
发布:whoami:asf站点
有关更多详细步骤,请参阅.asf.yaml文件.
现场管理
现场管理的基本要求是
- 只有提交者才能修改站点。
- 所有站点更改的通知都会发送到相关的项目邮件列表。
Infra支持这些工具来发布和维护Apache项目网站:
- 网站模板简化了不推荐使用的CMS上现有项目站点的迁移,以及新项目站点的创建。
- 鹈鹕和BuildBot简化项目网站的创建和发布。
- svnpubsub服务器自动发布指定svn文件夹的静态内容(例子)作为项目网站
http://project.apache.org
。只要满足上述要求,项目团队可以使用其想要的任何站点构建机制。
- pypubsub公司自动将指定Git存储库的静态内容用作项目的网站。基于Git的网站通常在存储库分支中维护,以发布为
https://project.apache.org
。项目可以从其主项目存储库承载站点。通常,这些将被构建为Jenkins或Buildbot作业(见下文)。我们建议您只有一个asf-site分支的编写器,以避免潜在的冲突。
- 对于使用Git存储库的网站,您可以添加.asf.yaml文件配置文件。该文件允许您设置简化网站更新和维护的说明。
构建工具
Infra提供以下构建工具:
- 詹金斯是一个支持构建、部署和自动化项目的开源自动化服务器。Jenkins上的Infra资源启动在这里.
- 构建机器人是一个作业调度系统:它对作业进行排队,在所需资源可用时执行作业,并报告结果。
登录中
编译站点时,作业的生成输出可以从Buildbot或Jenkins获得,具体取决于您使用的是哪种。
查找站点修订号
这仅适用于基于SVN的网站.
看看.修订
文件(例如,http://subversion.apache.org/.revision). 每次成功更新svn后,该文件都会更新。(如果更新正在进行或异常退出,.修订
不会改变。)
GitHub中的主题
如果您正在GitHub中管理ASF网站存储库,请添加网站
和<工具>
主题,其中<工具>
是用于生成网站的工具的名称,例如鹈鹕
或雨果
。这可以帮助其他正在寻找该工具使用示例的人通过以下查询找到您的存储库这个.
您可以使用.asf.yaml文件添加这些主题的机制。
提供对项目邮件存档mbox文件的公共访问
一些项目在其项目网站的顶部有一个“mail”目录。通过创建指向的符号链接来启用此功能/home/apmail/public-arch/$tlp.apache.org
在里面服务器子系统
.
查看更多关于项目邮件的注释.
使用项目的favicon
要为项目的网站使用自定义favicon,请添加图标文件
文件到站点的根目录。ASF羽毛出现在没有图标文件
文件。
最小化项目Maven或JavaDoc生成的站点中提交的更改数量
如果您正在使用服务器子系统
,如果更改的数量很大,尤其是如果文件的数量也很大,则提交的执行速度会非常慢。JavaDoc通常是这样的,Maven生成的站点在较小程度上也是这样。
要加快提交速度:
- 运行JavaDoc时,传递
-通知戳
选项。如果没有代码更改,这将避免在运行之间修改大多数文件。
- 使用不向输出添加时间戳的Maven皮肤。这可能需要自定义当前皮肤。
- 如果您在Project Info Reports插件中使用Maven依赖项报告,请使用2.7+版本的插件,以避免生成随机字符串。
- 如果您维护文档的历史版本,请始终将更改签入到单个“主干”中,然后使用
svn副本
标记或分支内容的操作,而不是签入完整的副本。
- 将模板中的“发布日期”和“版本”减少到真正必要或有用的程度。考虑在URL中使用“上次修改日期”和版本(除非隐含“最新”)。
- 最小化输出中可能经常更改但没有重要意义的Subversion关键字。这包括源代码中的关键字,这些关键字可能会呈现给JavaDoc或Maven JXR源交叉引用。
- 避免向项目站点发布经常更改的Maven报告。代码覆盖率、样式报告、静态分析等可以在CI服务器上生成工作副本,以便于开发人员查看。
预览网站
- 对于svnpubsub站点,请在提交之前查看svn签出中的本地文件。这些更改将在您提交后立即发布。
- 没有的预览模式
pypubsub公司
。您最好有一种在本地构建和测试网站的方法。