contribute/website/index.html - yetus - Git at Google

 <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <html>
     <head>
         <meta charset="utf-8">
         <title>Apache Yetus</title>
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
         <meta name="description" content="">
         <meta name="author" content="">

         <link href="../../assets/css/bootstrap.css" rel="stylesheet">
         <link href="../../assets/css/bootstrap-theme.css" rel="stylesheet">
         <link href="../../assets/css/font-awesome.css" rel="stylesheet">

         <!-- JS -->
         <script type="text/javascript" src="../../assets/js/jquery-2.1.4.min.js"></script>
         <script type="text/javascript" src="../../assets/js/bootstrap.js"></script>
   </head>
     <body>

 <div class="navbar navbar-inverse navbar-static-top" role="navigation">
     <div class="container">
         <div class="navbar-header">
             <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                 <span class="sr-only">Toggle navigation</span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
                 <span class="icon-bar"></span>
             </button>
             <a class="img-responsive pull-left" href="/">
                 <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
             </a>
         </div>
         <div class="navbar-collapse collapse">
             <ul class="nav navbar-nav">
                 <li><a href="/downloads/">Downloads</a>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu">
                       <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
                       <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
                       <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
                       <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
                       </li>
                       <li><a href="/documentation/history/">History of the Project</a>
                       </li>
                     </ul>
                 </li>
                 <li class="dropdown">
                     <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
                     <ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
                         </li>
                         <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
                         </li>
                     </ul>
                 </li>
                 <li>
                     <li class="dropdown">
                         <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
                         <ul class="dropdown-menu" role="menu">
                             <li><a href="https://www.apache.org">Apache Homepage</a>
                             </li>
                             <li><a href="https://www.apache.org/licenses/">Apache License</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
                             </li>
                             <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
                             </li>
                             <li><a href="https://www.apache.org/security/">Security</a>
                             </li>
                         </ul>
                     </li>
                 </li>
             </ul>
         </div>
         <!--/.nav-collapse -->
     </div>
 </div>

       <div class="container">
         <!---
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->

 <h1 id="maintaining-the-yetus-website">Maintaining the Yetus Website</h1>

 <!-- MarkdownTOC levels="1,2" autolink="true" -->

 <ul>
   <li><a href="#make-changes-in-asf-site-srcsource">Make changes in asf-site-src/source</a></li>
   <li><a href="#make-changes-to-api-docs">Make changes to API Docs</a></li>
   <li><a href="#generating-the-website">Generating the website</a></li>
   <li><a href="#live-development">Live Development</a></li>
   <li><a href="#publishing-the-site">Publishing the Site</a></li>
 </ul>

 <!-- /MarkdownTOC -->

 <p>We use <a href="https://middlemanapp.com/">Middleman</a> to generate the website content from markdown and other<br />
 dynamic templates.If you're interested in digging into how our site makes use of Middleman, or if you run into a problem, you should start<br />
 by reading <a href="https://middlemanapp.com/basics/install/">Middleman's excellent documentation</a>.</p>

 <div class="highlight"><pre class="highlight plaintext"><code>NOTE: The Docker container launched by `./start-build-env.sh` should have everything you need to maintain the website.

 NOTE: You MUST have run `mvn install` at least once prior to running `mvn site`.
 </code></pre></div>
 <p>The following steps assume you have a working ruby 2.7+ environment setup:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span><span class="nb">sudo </span>gem <span class="nb">install </span>bundler
 <span class="nv">$ </span><span class="nb">cd </span>asf-site-src
 <span class="nv">$ </span>bundle <span class="nb">install</span>
 </code></pre></div>
 <p>and a working Python 3.8 environment for <a href="/documentation/in-progress/releasedocmaker/">releasedocmaker</a>.</p>

 <h2 id="make-changes-in-asf-site-srcsource">Make changes in asf-site-src/source</h2>

 <p>Make any changes in the source directory:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nb">cd </span>asf-site-src/source
 vi contribute.html.md
 </code></pre></div>
 <h2 id="make-changes-to-api-docs">Make changes to API Docs</h2>

 <p>Optionally, you can update the generated API docs from other parts of the project. If they have been updated then the middleman build will pick up the changes.</p>

 <p>e.g. Precommit changes will be picked up by the Middleman build.</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nb">cd</span> ../precommit/core.d
 vi 01-common.sh
 </code></pre></div>
 <h2 id="generating-the-website">Generating the website</h2>

 <p>To generate the static website for Apache Yetus run the following command at the root directory:</p>

 <div class="highlight"><pre class="highlight shell"><code>mvn <span class="nt">--batch-mode</span> <span class="nb">install
 </span>mvn <span class="nt">--batch-mode</span> site site:stage &lt; /dev/null
 </code></pre></div>
 <p>Apache Yetus uses itself to build parts of its website. ('Flying our own airplanes')  This command will first generate a full build of Apache Yetus and create a static website in the <code>asf-site-src/target/site</code> sub directory and a tarball of the site in yetus-dist/target/. You can load it in a web browser, e.g. assuming you are still in the asf-site-src directory on OS X:</p>

 <div class="highlight"><pre class="highlight shell"><code>open asf-site-src/target/site/index.html
 </code></pre></div>
 <h2 id="live-development">Live Development</h2>

 <p>Live development of the site enables automatic reload when changes are saved.<br />
 To enable, run the following commands and then open a browser and navigate to<br />
 <a href="http://localhost:4567/">http://localhost:4567</a></p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nb">cd </span>asf-site-src
 bundle <span class="nb">exec </span>middleman
 </code></pre></div>
 <h2 id="publishing-the-site">Publishing the Site</h2>

 <p>Commit the publish directory to the asf-site branch. Presuming we start in a directory that holds your normal Yetus check out:</p>

 <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>git clone <span class="nt">--single-branch</span> <span class="nt">--branch</span> asf-site https://github.com/apache/yetus.git yetus-site
 <span class="nv">$ </span><span class="c"># Now build in the normal yetus check out</span>
 <span class="nv">$ </span><span class="nb">cd </span>yetus
 <span class="nv">$ </span>git fetch origin
 <span class="nv">$ </span>git checkout main
 <span class="nv">$ </span>git reset <span class="nt">--hard</span> origin/main
 <span class="nv">$ </span>git clean <span class="nt">-xdf</span>
 <span class="nv">$ </span>mvn <span class="nt">--batch-mode</span> <span class="nb">install</span>
 <span class="nv">$ </span>mvn <span class="nt">--batch-mode</span> site site:stage
 <span class="nv">$ </span>rsync <span class="nt">--quiet</span> <span class="nt">--checksum</span> <span class="nt">--inplace</span> <span class="nt">--recursive</span> yetus-dist/target/apache-yetus-<span class="k">${</span><span class="nv">project</span><span class="p">.version</span><span class="k">}</span><span class="nt">-SNAPSHOT-site</span>/ ../../yetus-site/
 <span class="nv">$ </span><span class="nb">cd</span> ../../yetus-site
 <span class="nv">$ </span><span class="c"># check the set of differences</span>
 <span class="nv">$ </span>git add <span class="nt">-p</span>
 <span class="nv">$ </span><span class="c"># Verify any new files are also added</span>
 <span class="nv">$ </span>git status
 <span class="nv">$ </span><span class="c"># Try to reference the commit hash on main that this publication assures we include</span>
 <span class="nv">$ </span>git commit <span class="nt">-m</span> <span class="s2">"git hash 6c6f6f6b696e6720746f6f20686172642c20796f"</span>
 <span class="nv">$ </span><span class="c"># Finally publish</span>
 <span class="nv">$ </span>git push origin asf-site
 </code></pre></div>
 <p>Publishing the website should be possible from the HEAD of the main branch under most circumstances. (See the <a href="../releases">Guide for Release Managing</a> for a notable time period where this won't be true.)<br />
 Documentation changes will be reviewed as they make their way into the main branch; updates to the <code>asf-site</code> branch are handled without further review.</p>

     </div>

 <div class="container">
     <hr>
     <footer class="footer">
         <div class="row-fluid">
             <div class="span12 text-left">
               <div class="span12">
                 Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
               </div>
             </div>

         </div>

     </footer>
 </div>

   </body>
 </html>
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<html>
	<head>
	<meta charset="utf-8">
	<title>Apache Yetus</title>
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta name="description" content="">
	<meta name="author" content="">

	<link href="../../assets/css/bootstrap.css" rel="stylesheet">
	<link href="../../assets/css/bootstrap-theme.css" rel="stylesheet">
	<link href="../../assets/css/font-awesome.css" rel="stylesheet">

	<!-- JS -->
	<script type="text/javascript" src="../../assets/js/jquery-2.1.4.min.js"></script>
	<script type="text/javascript" src="../../assets/js/bootstrap.js"></script>
	</head>
	<body>

	<div class="navbar navbar-inverse navbar-static-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="img-responsive pull-left" href="/">
	<img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../assets/img/yetus_logo.png" alt="Apache Yetus logo" />
	</a>
	</div>
	<div class="navbar-collapse collapse">
	<ul class="nav navbar-nav">
	<li><a href="/downloads/">Downloads</a>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li>
	<li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li>
	<li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li>
	<li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a>
	</li>
	<li><a href="/documentation/history/">History of the Project</a>
	</li>
	</ul>
	</li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu" aria-labelledby="drop1">
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a>
	</li>
	<li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a>
	</li>
	</ul>
	</li>
	<li>
	<li class="dropdown">
	<a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a>
	<ul class="dropdown-menu" role="menu">
	<li><a href="https://www.apache.org">Apache Homepage</a>
	</li>
	<li><a href="https://www.apache.org/licenses/">Apache License</a>
	</li>
	<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
	</li>
	<li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a>
	</li>
	<li><a href="https://www.apache.org/security/">Security</a>
	</li>
	</ul>
	</li>
	</li>
	</ul>
	</div>
	<!--/.nav-collapse -->
	</div>
	</div>

	<div class="container">
	<!---
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<h1 id="maintaining-the-yetus-website">Maintaining the Yetus Website</h1>

	<!-- MarkdownTOC levels="1,2" autolink="true" -->

	<ul>
	<li><a href="#make-changes-in-asf-site-srcsource">Make changes in asf-site-src/source</a></li>
	<li><a href="#make-changes-to-api-docs">Make changes to API Docs</a></li>
	<li><a href="#generating-the-website">Generating the website</a></li>
	<li><a href="#live-development">Live Development</a></li>
	<li><a href="#publishing-the-site">Publishing the Site</a></li>
	</ul>

	<!-- /MarkdownTOC -->

	<p>We use <a href="https://middlemanapp.com/">Middleman</a> to generate the website content from markdown and other<br />
	dynamic templates.If you're interested in digging into how our site makes use of Middleman, or if you run into a problem, you should start<br />
	by reading <a href="https://middlemanapp.com/basics/install/">Middleman's excellent documentation</a>.</p>

	<div class="highlight"><pre class="highlight plaintext"><code>NOTE: The Docker container launched by `./start-build-env.sh` should have everything you need to maintain the website.

	NOTE: You MUST have run `mvn install` at least once prior to running `mvn site`.
	</code></pre></div>
	<p>The following steps assume you have a working ruby 2.7+ environment setup:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span><span class="nb">sudo </span>gem <span class="nb">install </span>bundler
	<span class="nv">$ </span><span class="nb">cd </span>asf-site-src
	<span class="nv">$ </span>bundle <span class="nb">install</span>
	</code></pre></div>
	<p>and a working Python 3.8 environment for <a href="/documentation/in-progress/releasedocmaker/">releasedocmaker</a>.</p>

	<h2 id="make-changes-in-asf-site-srcsource">Make changes in asf-site-src/source</h2>

	<p>Make any changes in the source directory:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nb">cd </span>asf-site-src/source
	vi contribute.html.md
	</code></pre></div>
	<h2 id="make-changes-to-api-docs">Make changes to API Docs</h2>

	<p>Optionally, you can update the generated API docs from other parts of the project. If they have been updated then the middleman build will pick up the changes.</p>

	<p>e.g. Precommit changes will be picked up by the Middleman build.</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nb">cd</span> ../precommit/core.d
	vi 01-common.sh
	</code></pre></div>
	<h2 id="generating-the-website">Generating the website</h2>

	<p>To generate the static website for Apache Yetus run the following command at the root directory:</p>

	<div class="highlight"><pre class="highlight shell"><code>mvn <span class="nt">--batch-mode</span> <span class="nb">install
	</span>mvn <span class="nt">--batch-mode</span> site site:stage < /dev/null
	</code></pre></div>
	<p>Apache Yetus uses itself to build parts of its website. ('Flying our own airplanes') This command will first generate a full build of Apache Yetus and create a static website in the <code>asf-site-src/target/site</code> sub directory and a tarball of the site in yetus-dist/target/. You can load it in a web browser, e.g. assuming you are still in the asf-site-src directory on OS X:</p>

	<div class="highlight"><pre class="highlight shell"><code>open asf-site-src/target/site/index.html
	</code></pre></div>
	<h2 id="live-development">Live Development</h2>

	<p>Live development of the site enables automatic reload when changes are saved.<br />
	To enable, run the following commands and then open a browser and navigate to<br />
	<a href="http://localhost:4567/">http://localhost:4567</a></p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nb">cd </span>asf-site-src
	bundle <span class="nb">exec </span>middleman
	</code></pre></div>
	<h2 id="publishing-the-site">Publishing the Site</h2>

	<p>Commit the publish directory to the asf-site branch. Presuming we start in a directory that holds your normal Yetus check out:</p>

	<div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>git clone <span class="nt">--single-branch</span> <span class="nt">--branch</span> asf-site https://github.com/apache/yetus.git yetus-site
	<span class="nv">$ </span><span class="c"># Now build in the normal yetus check out</span>
	<span class="nv">$ </span><span class="nb">cd </span>yetus
	<span class="nv">$ </span>git fetch origin
	<span class="nv">$ </span>git checkout main
	<span class="nv">$ </span>git reset <span class="nt">--hard</span> origin/main
	<span class="nv">$ </span>git clean <span class="nt">-xdf</span>
	<span class="nv">$ </span>mvn <span class="nt">--batch-mode</span> <span class="nb">install</span>
	<span class="nv">$ </span>mvn <span class="nt">--batch-mode</span> site site:stage
	<span class="nv">$ </span>rsync <span class="nt">--quiet</span> <span class="nt">--checksum</span> <span class="nt">--inplace</span> <span class="nt">--recursive</span> yetus-dist/target/apache-yetus-<span class="k">${</span><span class="nv">project</span><span class="p">.version</span><span class="k">}</span><span class="nt">-SNAPSHOT-site</span>/ ../../yetus-site/
	<span class="nv">$ </span><span class="nb">cd</span> ../../yetus-site
	<span class="nv">$ </span><span class="c"># check the set of differences</span>
	<span class="nv">$ </span>git add <span class="nt">-p</span>
	<span class="nv">$ </span><span class="c"># Verify any new files are also added</span>
	<span class="nv">$ </span>git status
	<span class="nv">$ </span><span class="c"># Try to reference the commit hash on main that this publication assures we include</span>
	<span class="nv">$ </span>git commit <span class="nt">-m</span> <span class="s2">"git hash 6c6f6f6b696e6720746f6f20686172642c20796f"</span>
	<span class="nv">$ </span><span class="c"># Finally publish</span>
	<span class="nv">$ </span>git push origin asf-site
	</code></pre></div>
	<p>Publishing the website should be possible from the HEAD of the main branch under most circumstances. (See the <a href="../releases">Guide for Release Managing</a> for a notable time period where this won't be true.)<br />
	Documentation changes will be reviewed as they make their way into the main branch; updates to the <code>asf-site</code> branch are handled without further review.</p>

	</div>

	<div class="container">
	<hr>
	<footer class="footer">
	<div class="row-fluid">
	<div class="span12 text-left">
	<div class="span12">
	Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation.
	</div>
	</div>

	</div>

	</footer>
	</div>

	</body>
	</html>