| <!doctype html> |
| <html class="no-js" lang="en" dir="ltr"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="x-ua-compatible" content="ie=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <title>Managing your project web site - Apache Infrastructure Website</title> |
| <link href="/css/bootstrap.min.css" rel="stylesheet"> |
| <link href="/css/fontawesome.all.min.css" rel="stylesheet"> |
| <link href="/css/headerlink.css" rel="stylesheet"> |
| <script src="/highlight/highlight.min.js"></script> </head> |
| <body class="d-flex flex-column h-100"> |
| <main class="flex-shrink-0"> |
| <div> |
| |
| <!-- nav bar --> |
| <nav class="navbar navbar-expand-lg navbar-dark bg-dark" aria-label="Fifth navbar example"> |
| <div class="container-fluid"> |
| <a class="navbar-brand" href="/"><img src="/images/feather.png" style="height: 32px;"/> Apache Infrastructure</a> |
| <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarADP" aria-controls="navbarADP" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| |
| <div class="collapse navbar-collapse" id="navbarADP"> |
| <ul class="navbar-nav me-auto mb-2 mb-lg-0"> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">About</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/team.html">About the team</a></li> |
| <li><a class="dropdown-item" href="/roundtable.html">The Infrastructure Roundtable</a></li> |
| <li><a class="dropdown-item" href="/blog/">The Infrastructure Blog</a></li> |
| </ul> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/policies.html">Policies</a> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Services and Tools</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/services.html">Services and Tools</a></li> |
| <li><a class="dropdown-item" href="/machines.html">Machines and Fingerprints</a></li> |
| <li><a class="dropdown-item" href="https://blocky.apache.org/">Blocky</a></li> |
| <li><a class="dropdown-item" href="https://app.datadoghq.com/account/login?next=%2Finfrastructure">DataDog</a></li> |
| <li><a class="dropdown-item" href="https://whimsy.apache.org/roster/committer/" target="_blank">Committer Search</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/doc.html">Contribute</a></li> |
| <li><a class="dropdown-item" href="/infra-volunteer.html">Volunteer with Infra</a></li> |
| <li><a class="dropdown-item" href="/how-to-mirror.html">Become an ASF download mirror</a></li> |
| <li><a class="dropdown-item" href="/hosting-external-agent.html">Host a Jenkins or Buildbot agent</a></li> |
| |
| </ul> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/stats.html">Status</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/contact.html">Contact Us</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <!-- page contents --> |
| <div id="contents"> |
| <div class="bg-white p-5 rounded"> |
| <div class="col-sm-8 mx-auto"> |
| <h1> |
| Managing your project web site |
| </h1> |
| <p>Every Apache project or podling has a website hosted at <code>apache.org</code>. Apache provides tools to support it. Each project decides how their website looks, its contents, how they maintain it, and what software they use to support it, as long as the result is static files that our public web servers can make available to browsers. We also have limited support for .htaccess files and CGI scripts.</p> |
| <h2>Contents</h2> |
| <ul> |
| <li><a href="#planning">Planning the project website</a></li> |
| <li><a href="#default">Creating the website</a></li> |
| <li><a href="#sitemanagement">Site management</a></li> |
| <li><a href="#preview">Previewing the website</a></li> |
| </ul> |
| |
| <h2 id="planning">Planning the project website<a class="headerlink" href="#planning" title="Permanent link">¶</a></h2> |
| |
| <p>Your project team wants to build an excellent application that solves a problem, simplifies a process, or breaks new ground. You also want people to find it, try it, and adopt it. Your project website is key to attracting and engaging both contributors to project development and people and organizations that will become part of your user community.</p> |
| <p>Your website <strong>must</strong></p> |
| <ul> |
| <li>satisfy the <a href="https://www.apache.org/foundation/marks/pmcs" target="_blank">Apache branding requirements</a>, in particular that <a href="https://www.apache.org/foundation/marks/pmcs#navigation" target="_blank">certain links</a> appear on the site's landing page, in whatever navigation structure the site uses. Whimsy's <a href="https://whimsy.apache.org/site/" target="_blank">Apache Project Website Checks</a> tool periodically reviews all top-level project (TLP) websites to provide a report on how well they comply with that policy, and to identify issues that a project may need to address.</li> |
| <li>comply with the Infrastructure team's <a href="project-site-policy.html">project site policy</a>.</li> |
| </ul> |
| <p>The site also <strong>should</strong></p> |
| <ul> |
| <li>explain what your project's product does.</li> |
| <li>pitch how your product solves a problem or creates a new opportunity.</li> |
| <li>invite people to get involved in the development team.</li> |
| <li>offer an easy way to download the latest builds of the product that you want the public to use.</li> |
| <li>provide documentation that will help people not part of the project understand how to get started with the product and how to keep going.</li> |
| <li>describe how the project team works, and its connection to the Apache Software Foundation.</li> |
| <li>explain how people can get in touch with the project to provide feedback or ask questions.</li> |
| </ul> |
| <p>Once you have outlined the content that will be on the website, and decided how and where to display it, you need to decide how to build the site.</p> |
| <h2 id="default">Creating the website<a class="headerlink" href="#default" title="Permanent link">¶</a></h2> |
| |
| <p>Projects are free to choose their own styles and layout for websites, and have a range of options for actually creating the pages. The goal is to create an informative and useful <strong>static</strong> HTML website that can engage visitors, explain your project to them, and provide download links and documentation so they can use your project's applications.</p> |
| <h3>JavaScript issues</h3> |
| <p>Many TLP sites use JavaScript (JS) to provide functions ranging from menu navigation to animations and image galleries. While JS can enhance the site experience for most visitors, it can pose problems:</p> |
| <ol> |
| <li><strong>Visitors who have scripting languages disabled</strong>. General-interest sites can have as much as 10% of their site visitors with JS disabled in their browsers; that percentage is probably lower for sites aimed at a more technical audience. Make sure your site provides access to the essential information it must deliver even if the visitor's browser has disabled scripting languages.</li> |
| <li><strong>Visitors who use assistive devices to read and work with web pages</strong>. A web search on "JavaScript and assistive readers" will provide helpful information on writing and deploying JS in ways that cause the fewest issues for people using assistive devices to access your project website. The <a href="http://www.cynthiasays.com/" target="_blank">Cynthia Says</a> site can help you check your website for compliance with accessibility guidelines, including JavaScript issues.</li> |
| </ol> |
| <h3>1. Website-building options</h3> |
| <h4>Pelican</h4> |
| <p><a href="https://docs.getpelican.com/en/stable/" target="_blank">Pelican</a> is a static site generator written in Python. Highlights include:</p> |
| <ul> |
| <li>Write your content directly with your editor of choice in reStructuredText or Markdown formats.</li> |
| <li>Includes a simple CLI tool to (re)generate your site.</li> |
| <li>Easy to interface with distributed version control systems and web hooks.</li> |
| <li>Completely static output is easy to host anywhere.</li> |
| </ul> |
| <p>Pelican has paths to <a href="https://docs.getpelican.com/en/stable/importer.html#import" target="_blank">migrate existing websites from many technologies</a>, including Blogger, Dotclear, Posterous, Tumblr, WordPress, and RSS/Atom.</p> |
| <p>Any ASF project can use the <a href="asf-pelican.html"><strong>ASF-Pelican template</strong></a> as the basis for their project website. </p> |
| <p>See a how-to on using <a href="pelican-buildbot.html">Pelican and Buildbot</a> to develop and deploy a project website.</p> |
| <p>Pelican supports both flat websites and those that have subdirectories. For the latter, Pelican provides a <a href="https://github.com/akhayyat/pelican-page-hierarchy" target="_blank">plugin</a>.</p> |
| <p>Browse a <a href="https://github.com/getpelican/pelican-plugins/" target="_blank">collection of Pelican plugins</a> to find others that support functionality you want to add to your site. </p> |
| <p>This <a href="https://github.com/search?q=topic%3Apelican+org%3Aapache&type=Repositories" target="_blank">GitHub query</a> returns ASF repositories |
| which have the <code>pelican</code> Topic. You can review them as examples of Pelican in action.</p> |
| <h4>Jekyll</h4> |
| <p><a href="https://jekyllrb.com/" target="_blank">Jekyll</a> is a straightforward tool for developing blogs or static websites using Markdown, and it is easy to deploy the resulting website as GitHub Pages. There are many tutorials online about doing this.</p> |
| <h4>Hugo</h4> |
| <p>At least <a href="https://github.com/search?q=topic%3Ahugo+org%3Aapache&type=Repositories" target="_blank">six ASF projects</a> use <a href="https://gohugo.io/" target="_blank">Hugo</a>, an open-source framework for building static web sites.</p> |
| <h4>JBake</h4> |
| <p>At least <a href="https://github.com/search?q=topic%3Ajbake+org%3Aapache&type=Repositories" target="_blank">two ASF projects</a> use <a href="https://jbake.org/" target="_blank">JBake</a>, a Java-based tool for building static web sites.</p> |
| <h4>MKDocs</h4> |
| <p><a href="https://www.mkdocs.org/" target="_blank">MKDocs</a> is a static site generator designed for creating project documentation. However, at least one ASF project uses it to build their entire project website. See <a href="asfyaml-mkdocs.html">this note</a> on the build sequence to use to preserve your project site's <a href="asf-yaml.html">.asf.yaml</a> file.</p> |
| <h4>Basic website template in Markdown</h4> |
| <p>If you'd like to get started with an easy-to-use, <a href="https://github.github.com/gfm/" target="_blank">Markdown</a>-based site that many projects have used, see the <a href="https://github.com/apache/apache-website-template" target="_blank">sample Apache project website</a> repository, which has many useful features and instructions for using <code>svnpubsub</code>.</p> |
| <h4>HTML files</h4> |
| <p>You can use any other tool that generates static HTML pages, or hand-code those pages. You then check them into your project's website repository. The check-in will trigger a site update.</p> |
| <h4>Custom website directives using .htaccess files</h4> |
| <p>Project websites can make use of .htaccess files for setting up custom redirects and other tweaks to the handling of requests. The default <a href="https://httpd.apache.org/docs/2.4/mod/core.html#allowoverride">AllowOverride</a> setting is <code>All</code>, |
| which generally enables any sort of redirects or rewrites (using <code>RewriteRule</code>, <code>Redirect</code>, etc.). Some project websites have custom settings in their dedicated virtual host configuration, which may require asking the Infrastructure Team for assistance. If you are in doubt, ask.</p> |
| <h3>Tools not supported</h3> |
| <h4>GitHub Pages</h4> |
| <p>Infra does not have a structure in place to support using <a href="github-pages.html">GitHub Pages</a> for project websites.</p> |
| <h4>Apache CMS</h4> |
| <p>The Apache CMS, which projects used to build and deploy their websites since 2010, is no longer available as of July 31, 2021. All projects that used it, including the main Apache website, have moved or must move to other technologies. Those that linger will find at some point that they can no longer update their website. See the notes in the section on site management tools, below.</p> |
| <h3>2. Website repository</h3> |
| <p>If you don't have a web site repository for your project yet, you can create one using <a href="https://selfserve.apache.org/" target="_blank">Self-serve</a>.</p> |
| <p>The convention is to name the repository <code>$project-site.git</code>, for instance <code>httpd-site.git</code>.</p> |
| <p>Copy whatever you need to start a build into the master branch of the new repository. This will act as the base of the build process.</p> |
| <h3>3. The build process</h3> |
| <p>Configure Pelican or Jekyll to build the site automatically when its contents change, using <a href="asf-yaml.html">.asf.yaml</a> and Buildbot. </p> |
| <h3>4. A staging website</h3> |
| <p>Using <a href="asf-yaml.html">.asf.yaml</a> with a Git repository, once you have your generated web site committed and pushed to a branch, you can set up a staging web site to test your changes before publishing them to your main web site.</p> |
| <p>To do so, add or edit <code>.asf.yaml</code> in the staging branch (where the build output is generated) and add the following (assuming your staging branch is asf-staging):</p> |
| <div class="highlight"><pre><span></span><code><span class="n">staging</span><span class="o">:</span> |
| <span class="w"> </span><span class="n">profile</span><span class="o">:</span><span class="w"> </span><span class="o">~</span> |
| <span class="w"> </span><span class="n">whoami</span><span class="o">:</span><span class="w"> </span><span class="n">asf</span><span class="o">-</span><span class="n">staging</span> |
| </code></pre></div> |
| |
| <p>Upon commits to this branch, your staging web site will appear with the latest output at: <code>https://$project.staged.apache.org/</code> |
| For more details, see <a href="asf-yaml.html">.asf.yaml</a>.</p> |
| <h3>5. Publishing</h3> |
| <p>When you are ready to publish a branch of your Git web site repository to your project web site, you can use <code>.asf.yaml</code>:</p> |
| <div class="highlight"><pre><span></span><code><span class="n">publish</span><span class="o">:</span> |
| <span class="w"> </span><span class="n">whoami</span><span class="o">:</span><span class="w"> </span><span class="n">asf</span><span class="o">-</span><span class="n">site</span> |
| </code></pre></div> |
| |
| <p>For more detailed procedures, see see <a href="asf-yaml.html">.asf.yaml</a>.</p> |
| <h2 id="sitemanagement">Site management</h2> |
| |
| <p>The basic requirements for site management are that </p> |
| <ul> |
| <li>only committers should be able to modify the site.</li> |
| <li>notifications of all site changes are sent to the relevant project mailing lists.</li> |
| </ul> |
| <h3 id="tools">Management tools<a class="headerlink" href="#tools" title="Permanent link">¶</a></h3> |
| |
| <p>Infra supports these tools for publishing and maintaining Apache project websites:</p> |
| <ul> |
| <li><strong><a href="asf-pelican.html">Site template</a></strong> streamlines migration of an existing project site on the deprecated CMS, and creation of new project sites.</li> |
| <li><strong><a href="pelican-buildbot.html">Pelican and BuildBot</a></strong> streamline creating and publishing your project website.</li> |
| <li><strong>svnpubsub</strong> automatically publishes the static contents of a designated svn folder (<a href="https://svn.apache.org/repos/asf/ant/site/ant/production/" target="_blank">example</a>) as the project web site at <code>http://project.apache.org</code>. The project team can use any site build mechanism it wants as long as the above requirements are met.</li> |
| <li><a href="pypubsub.html"><strong>pypubsub</strong></a> automatically serves the static contents of a designated Git repository as the website for a project. Git-based websites are typically maintained in a repository branch to be published as <code>https://project.apache.org</code>. A project can host the site from its primary project repository. Typically these will be built as a Jenkins or a Buildbot job (see below). We recommend that you only have a single writer to the asf-site branch to avoid potential conflicts.</li> |
| <li>For <strong>websites using a Git repository</strong>, you can add an <a href="asf-yaml.html">.asf.yaml</a> configuration file. The file lets you set instructions that simplify updating and maintaining the site.</li> |
| </ul> |
| <h3>Build tools</h3> |
| <p>Infra provides these build tools:</p> |
| <ul> |
| <li><strong>Jenkins</strong> is an open-source automation server that supports building, deploying and automating a project. Infra resources on Jenkins start <a href="https://cwiki.apache.org/confluence/display/INFRA/Jenkins" target="_blank">here</a>. </li> |
| <li><strong>Buildbot</strong> is a job scheduling system: it queues jobs, executes the jobs when the required resources are available, and reports the results. </li> |
| </ul> |
| <h3 id="logging">Logging<a class="headerlink" href="#logging" title="Permanent link">¶</a></h3> |
| |
| <p>The build output from your job when you compile your site is available from either Buildbot or Jenkins, depending on which you use.</p> |
| <h3 id="svnpubsub-revision">Finding the site revision number<a class="headerlink" href="#svnpubsub-revision" title="Permanent link">¶</a></h3> |
| |
| <p>This only applies to <em>SVN based websites</em>.</p> |
| <p>Look at the <code>.revision</code> file at the root of your site (for example, <a href="http://subversion.apache.org/.revision" target="_blank">http://subversion.apache.org/.revision</a>). That file updates after every successful svn update. (If the update is underway or exited abnormally, <code>.revision</code> won't have changed.)</p> |
| <h3>Topics in GitHub</h3> |
| <p>If you're managing an ASF website repository in GitHub, please add <code>website</code> and <code><TOOL></code> Topics to it, where <code><TOOL></code> is the name of the tool you are using to generate the website, like <code>pelican</code> or <code>hugo</code>. This helps others who are looking for an example of use of that tool find your repository, with queries like |
| <a href="https://github.com/search?q=org%3Aapache+topic%3Ahugo" target="_blank">this one</a>.</p> |
| <p>You can use the <a href="asf-yaml.html">.asf.yaml</a> mechanism to add those Topics.</p> |
| <h3 id="mail">Providing public access to the project's mail archive mbox files<a class="headerlink" href="#mail" title="Permanent link">¶</a></h3> |
| |
| <p>Some projects have a "mail" directory at the top of their project website. Enable this by creating a symbolic link to <code>/home/apmail/public-arch/$tlp.apache.org</code> in <code>svnpubsub</code>.</p> |
| <p>See more <a href="https://apache.org/dev/#mail" target="_blank">notes about project mail</a>.</p> |
| <h3 id="feather">Using the project's favicon<a class="headerlink" href="#feather" title="Permanent link">¶</a></h3> |
| |
| <p>To use a custom favicon for your project's website, add the <code>favicon.ico</code> file to your site's root directory. The ASF feather appears for project sites that don't have a <code>favicon.ico</code> file.</p> |
| <h3 id="generated">Minimizing the number of changes committed in the project's Maven- or JavaDoc- generated site<a class="headerlink" href="#generated" title="Permanent link">¶</a></h3> |
| |
| <p>If you are using <code>svnpubsub</code>, the commit performs very slowly if the number of changes is large, particularly if the number of files is also large. This is often the case with JavaDoc, and to a lesser extent with Maven-generated sites. </p> |
| <p>To speed up the commit:</p> |
| <ul> |
| <li>When running JavaDoc, pass the <code>-notimestamp</code> option. This will avoid most files from being modified between runs if there haven't been code changes.</li> |
| <li>Use a Maven skin that doesn't add a timestamp to the output. This may require customizing the current skins.</li> |
| <li>If you use the Maven dependencies report in the Project Info Reports plugin, use version 2.7+ of the plugin to avoid random strings being generated.</li> |
| <li>If you maintain historical versions of documentation, always check changes in to a single "trunk", then use an <code>svn copy</code> operation to tag or branch the content, rather than checking in a complete copy.</li> |
| <li>Minimize use of "publish date" and "version" in templates to those that are truly necessary or helpful. Consider using a "last modified date" and version in the URL instead (unless "latest" is implied).</li> |
| <li>Minimize Subversion keywords in the output that may change frequently without significant meaning. This includes keywords in source code that may be rendered to JavaDoc or a Maven JXR source cross-reference.</li> |
| <li>Avoid publishing Maven reports that change constantly to the project site. Code coverage, style reports, static analysis, etc. can be generated into working copies on the CI server instead for easy developer viewing.</li> |
| </ul> |
| <h2 id="preview">Previewing the website<a class="headerlink" href="#preview" title="Permanent link">¶</a></h2> |
| |
| <ul> |
| <li>For svnpubsub sites, review the local files in your svn checkout before committing them. The changes will be published immediately after you commit them.</li> |
| <li>There is no preview mode for <code>pypubsub</code>. You should ideally have a way to build and test the website locally.</li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <!-- footer --> |
| <div class="row"> |
| <div class="large-12 medium-12 columns"> |
| <p style="font-style: italic; font-size: 0.8rem; text-align: center;"> |
| Copyright 2024, <a href="https://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> |
| Apache® and the Apache feather logo are trademarks of The Apache Software Foundation... |
| </p> |
| </div> |
| </div> |
| <script type="application/ecmascript" src="/js/bootstrap.bundle.min.js" integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3"></script> </div> |
| </main> |
| <script>hljs.initHighlightingOnLoad();</script> |
| </body> |
| </html> |
