flink-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rmetz...@apache.org
Subject svn commit: r1613694 - in /incubator/flink: how-to-contribute.md site/how-to-contribute.html
Date Sat, 26 Jul 2014 18:03:00 GMT
Author: rmetzger
Date: Sat Jul 26 18:02:59 2014
New Revision: 1613694

URL: http://svn.apache.org/r1613694
Log:
[FLINK-1035] document how to contribute to the website

Modified:
    incubator/flink/how-to-contribute.md
    incubator/flink/site/how-to-contribute.html

Modified: incubator/flink/how-to-contribute.md
URL: http://svn.apache.org/viewvc/incubator/flink/how-to-contribute.md?rev=1613694&r1=1613693&r2=1613694&view=diff
==============================================================================
--- incubator/flink/how-to-contribute.md (original)
+++ incubator/flink/how-to-contribute.md Sat Jul 26 18:02:59 2014
@@ -19,9 +19,11 @@ In addition, you can find a list of idea
 
 ## Contributing Code & Documentation
 
-This section gives you a brief introduction in how to contribute code and documentation to
Flink. We maintain both the code and the documentation in the same repository, so the process
is essentially the same for both. We use [git](http://git-scm.com/) for the code and documentation
version control.
+This section gives you a brief introduction in how to contribute code and documentation to
Flink. We maintain both the code and the documentation in the same repository, so the process
is essentially the same for both. We use [git](http://git-scm.com/) for the code and documentation
version control. The documentation is located in the `docs/` subdirectory of the git repository.
 
-The Flink project accepts code contributions though the [GitHub Mirror](https://github.com/apache/incubator-flink),
in the form of [Pull Requests](https://help.github.com/articles/using-pull-requests). Pull
requests are basically a simpler way of offering a patch, by providing a pointer to a code
branch that contains the change. It is also possible to attach a patch to a JIRA issue.
+The Flink project accepts code contributions though the [GitHub Mirror](https://github.com/apache/incubator-flink),
in the form of [Pull Requests](https://help.github.com/articles/using-pull-requests). Pull
requests are basically a simpler way of offering a patch, by providing a pointer to a code
branch that contains the change. 
+
+It is also possible to attach a patch to a [JIRA]({{site.FLINK_ISSUES_URL}}) issue.
 
 
 ### Setting up the Infrastructure and Creating a Pull Request
@@ -92,8 +94,45 @@ cd docs
 ```
 Now, open your browser at `http://localhost:4000` and check out the pages you changed.
 
+## Contribute changes to the Website
+
+The website of Apache Flink is hosted in a [Subversion (SVN)](https://subversion.apache.org/)
repository. The repository is located here: [https://svn.apache.org/repos/asf/incubator/flink/](https://svn.apache.org/repos/asf/incubator/flink/).
+
+To make changes to the website, you have to checkout the source code of it first:
+```
+svn checkout https://svn.apache.org/repos/asf/incubator/flink/
+cd flink
+```
+
+The `flink` repository contains the files that we use to build the website. We use [Jekyll](http://jekyllrb.com/)
to generate static HTML files for the website. 
+
+### Files and Directories in the SVN repository
+
+The files and directories in the SVN repository have the following roles:
+- all files ending with `.md` are [Markdown](http://daringfireball.net/projects/markdown/)
files. Those are the input for the HTML files.
+- regular directories (not starting with an underscore (`_`)) contain also `.md` files. The
directory structure is also represented in the generated HTML files.
+- the `_posts` directory contains one Markdown file for each blog post on the website. To
contribute a post, just add a new file there.
+- the `_includes/` directory contains includeable files such as the navigation bar or the
footer.
+- the `docs/` directory contains copies of the documentation of Flink for different releases.
There is a directory inside `docs/` for each stable release and the latest SNAPSHOT version.
The build script is taking care of the maintenance of this directory.
+- the `site/` directory contains the generated HTML files from Jekyll. It is important to
place the files in this directory since the Apache Infrastructure to host the Flink website
is pulling the HTML content from his directory. (For committers: When pushing changes to the
website svn, push also the updates in the `site/` directory!)
+- see the section below for he `build.sh` script
 
 
+### The `build.sh` script
+
+The `build.sh` script creates HTML files from the input Markdown files. Use the `-p` flag
to let Jekyll serve a **p**review of the website on http://localhost:4000/.
+
+The build script also takes care of maintaining the `docs/` directory. Set the `-u` flag
to **u**pdate documentation. This includes fetching the Flink git repository and copying different
versions of the documentation.
+
+### Submit a patch
+
+To contribute back your changes to the main project, create a patch that you can attach to
a JIRA issue.
+
+```
+svn diff > improvement.patch
+```
+Upload the `.patch` file to a JIRA issue.
+
 ## How to become a committer
 
 There is no strict protocol for becoming a committer. Candidates for new committers are typically
people that are active contributors and community members.

Modified: incubator/flink/site/how-to-contribute.html
URL: http://svn.apache.org/viewvc/incubator/flink/site/how-to-contribute.html?rev=1613694&r1=1613693&r2=1613694&view=diff
==============================================================================
--- incubator/flink/site/how-to-contribute.html (original)
+++ incubator/flink/site/how-to-contribute.html Sat Jul 26 18:02:59 2014
@@ -114,6 +114,20 @@
 </ul>
 </li>
 <li>
+<a href="#contribute-changes-to-the-website">Contribute changes to the Website</a>
+<ul>
+<li>
+<a href="#files-and-directories-in-the-svn-repository">Files and Directories in the
SVN repository</a>
+</li>
+<li>
+<a href="#the-build.sh-script">The &lt;code&gt;build.sh&lt;/code&gt;
script</a>
+</li>
+<li>
+<a href="#submit-a-patch">Submit a patch</a>
+</li>
+</ul>
+</li>
+<li>
 <a href="#how-to-become-a-committer">How to become a committer</a>
 <ul>
 <li>
@@ -136,9 +150,11 @@
 
 <h2 id="contributing-code-&amp;-documentation">Contributing Code &amp; Documentation</h2>
 
-<p>This section gives you a brief introduction in how to contribute code and documentation
to Flink. We maintain both the code and the documentation in the same repository, so the process
is essentially the same for both. We use <a href="http://git-scm.com/">git</a>
for the code and documentation version control.</p>
+<p>This section gives you a brief introduction in how to contribute code and documentation
to Flink. We maintain both the code and the documentation in the same repository, so the process
is essentially the same for both. We use <a href="http://git-scm.com/">git</a>
for the code and documentation version control. The documentation is located in the <code>docs/</code>
subdirectory of the git repository.</p>
 
-<p>The Flink project accepts code contributions though the <a href="https://github.com/apache/incubator-flink">GitHub
Mirror</a>, in the form of <a href="https://help.github.com/articles/using-pull-requests">Pull
Requests</a>. Pull requests are basically a simpler way of offering a patch, by providing
a pointer to a code branch that contains the change. It is also possible to attach a patch
to a JIRA issue.</p>
+<p>The Flink project accepts code contributions though the <a href="https://github.com/apache/incubator-flink">GitHub
Mirror</a>, in the form of <a href="https://help.github.com/articles/using-pull-requests">Pull
Requests</a>. Pull requests are basically a simpler way of offering a patch, by providing
a pointer to a code branch that contains the change. </p>
+
+<p>It is also possible to attach a patch to a <a href="https://issues.apache.org/jira/browse/FLINK">JIRA</a>
issue.</p>
 
 <h3 id="setting-up-the-infrastructure-and-creating-a-pull-request">Setting up the Infrastructure
and Creating a Pull Request</h3>
 
@@ -207,6 +223,43 @@ git rebase master
 </code></pre></div>
 <p>Now, open your browser at <code>http://localhost:4000</code> and check
out the pages you changed.</p>
 
+<h2 id="contribute-changes-to-the-website">Contribute changes to the Website</h2>
+
+<p>The website of Apache Flink is hosted in a <a href="https://subversion.apache.org/">Subversion
(SVN)</a> repository. The repository is located here: <a href="https://svn.apache.org/repos/asf/incubator/flink/">https://svn.apache.org/repos/asf/incubator/flink/</a>.</p>
+
+<p>To make changes to the website, you have to checkout the source code of it first:</p>
+<div class="highlight"><pre><code class="language-text" data-lang="text">svn
checkout https://svn.apache.org/repos/asf/incubator/flink/
+cd flink
+</code></pre></div>
+<p>The <code>flink</code> repository contains the files that we use to
build the website. We use <a href="http://jekyllrb.com/">Jekyll</a> to generate
static HTML files for the website. </p>
+
+<h3 id="files-and-directories-in-the-svn-repository">Files and Directories in the SVN
repository</h3>
+
+<p>The files and directories in the SVN repository have the following roles:</p>
+
+<ul>
+<li>all files ending with <code>.md</code> are <a href="http://daringfireball.net/projects/markdown/">Markdown</a>
files. Those are the input for the HTML files.</li>
+<li>regular directories (not starting with an underscore (<code>_</code>))
contain also <code>.md</code> files. The directory structure is also represented
in the generated HTML files.</li>
+<li>the <code>_posts</code> directory contains one Markdown file for each
blog post on the website. To contribute a post, just add a new file there.</li>
+<li>the <code>_includes/</code> directory contains includeable files such
as the navigation bar or the footer.</li>
+<li>the <code>docs/</code> directory contains copies of the documentation
of Flink for different releases. There is a directory inside <code>docs/</code>
for each stable release and the latest SNAPSHOT version. The build script is taking care of
the maintenance of this directory.</li>
+<li>the <code>site/</code> directory contains the generated HTML files
from Jekyll. It is important to place the files in this directory since the Apache Infrastructure
to host the Flink website is pulling the HTML content from his directory. (For committers:
When pushing changes to the website svn, push also the updates in the <code>site/</code>
directory!)</li>
+<li>see the section below for he <code>build.sh</code> script</li>
+</ul>
+
+<h3 id="the-build.sh-script">The <code>build.sh</code> script</h3>
+
+<p>The <code>build.sh</code> script creates HTML files from the input Markdown
files. Use the <code>-p</code> flag to let Jekyll serve a <strong>p</strong>review
of the website on <a href="http://localhost:4000/">http://localhost:4000/</a>.</p>
+
+<p>The build script also takes care of maintaining the <code>docs/</code>
directory. Set the <code>-u</code> flag to <strong>u</strong>pdate
documentation. This includes fetching the Flink git repository and copying different versions
of the documentation.</p>
+
+<h3 id="submit-a-patch">Submit a patch</h3>
+
+<p>To contribute back your changes to the main project, create a patch that you can
attach to a JIRA issue.</p>
+<div class="highlight"><pre><code class="language-text" data-lang="text">svn
diff &gt; improvement.patch
+</code></pre></div>
+<p>Upload the <code>.patch</code> file to a JIRA issue.</p>
+
 <h2 id="how-to-become-a-committer">How to become a committer</h2>
 
 <p>There is no strict protocol for becoming a committer. Candidates for new committers
are typically people that are active contributors and community members.</p>



Mime
View raw message