This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-training.git
The following commit(s) were added to refs/heads/asf-site by this push:
new a5c49dc Site checkin for project Training: Website
a5c49dc is described below
commit a5c49dc35f952d868ab2b33ab0bc520d93f04e11
Author: jenkins <[email protected]>
AuthorDate: Thu May 23 23:09:17 2019 +0000
Site checkin for project Training: Website
---
developers/contributing.html | 131 +++++++++++--------------------------------
1 file changed, 34 insertions(+), 97 deletions(-)
diff --git a/developers/contributing.html b/developers/contributing.html
index 24598ce..db699e4 100644
--- a/developers/contributing.html
+++ b/developers/contributing.html
@@ -111,16 +111,17 @@
<ul id="toc" class="nav navbar-nav">
<li
class="toplevel"><a href="#_toc_contributing1"
title="Contributing">Contributing</a></li>
<li class="toplevel"><a
href="#_toc_forms_of_contribution1" title="Forms of contribution">Forms of
contribution</a></li>
+ <li class="toplevel"><a
href="#_toc_finding_a_project1" title="Finding a Project">Finding a
Project</a></li>
<li class="dropdown">
- <a href="#" title="Pull-Requests"
class="dropdown-toggle" role="button" data-toggle="dropdown">Pull-Requests <b
class="caret"></b></a>
+ <a href="#" title="Code Contributions"
class="dropdown-toggle" role="button" data-toggle="dropdown">Code Contributions
<b class="caret"></b></a>
<ul class="dropdown-menu" role="menu">
<!-- Repeat the item, otherwise it is not
clickable as the dropdown root -->
- <li><a href="#_toc_pull-requests"
title="Pull-Requests">Pull-Requests</a></li>
+ <li><a href="#_toc_code_contributions1"
title="Code Contributions">Code Contributions</a></li>
<li class="divider"></li>
- <li><a
href="#_toc_keeping_your_fork_up_to_date1" title="Keeping your fork up to
date">Keeping your fork up to date</a></li>
+ <li><a
href="#_toc_review_process1" title="Review Process">Review Process</a></li>
</ul>
</li>
- <li class="toplevel"><a href="#_toc_bug_reports1"
title="Bug Reports">Bug Reports</a></li>
+ <li class="toplevel"><a href="#_toc_issue_reports1"
title="Issue Reports">Issue Reports</a></li>
<li class="toplevel"><a href="#_toc_documentation1"
title="Documentation">Documentation</a></li>
</ul>
</div>
@@ -140,137 +141,73 @@
<div class="sect2">
<h3 id="_toc_forms_of_contribution1">Forms of contribution</h3>
<div class="paragraph">
- <p>There are multiple forms in which you can become involved with the
Apache Training project.</p>
+ <p>The Apache Training (Incubating) project welcomes contributions in all
forms, sizes, and shapes. Below you can find a small list of possible ways that
you can contribute if you have some spare time and want to get involved.</p>
</div>
<div class="paragraph">
- <p>These usually are, but are not limited to:</p>
+ <p>This list is by no means finite. There are without doubt dozens of
other useful ways that you can pick, please do not let this limit your
creativity!</p>
</div>
<div class="ulist">
<ul>
- <li> <p>Submitting Pull Requests</p> </li>
+ <li> <p>Adding to the webpage</p> </li>
<li> <p>Filing Bug-Reports</p> </li>
+ <li> <p>Converting donated materials</p> </li>
<li> <p>Active communication on our mailing lists</p> </li>
<li> <p>Promoting the project (articles, blog posts, talks at
conferences)</p> </li>
- <li> <p>Documentation</p> </li>
+ <li> <p>Writing documentation</p> </li>
</ul>
</div>
</div>
<div class="sect2">
- <h3 id="_toc_pull-requests">Pull-Requests</h3>
+ <h3 id="_toc_finding_a_project1">Finding a Project</h3>
<div class="paragraph">
- <p>The simplest way to submit code changes is via a GitHub
pull-request.</p>
+ <p>If you want to get involved, but do not have a specific project in mind
please feel free to check our issue tracker for <a
href="https://issues.apache.org/Jira/issues/?jql=project%20%3D%20TRAINING%20AND%20labels%20%3D%20beginner%20AND%20assignee%20in%20(EMPTY)">unassigned
issues with the <em>beginner</em> label</a>. These should be good candidates
to get your feet wet and gather some experience before tackling larger
issues.</p>
</div>
<div class="paragraph">
- <p>In order to do this first create a GitHub account and sign into your
account.</p>
- </div>
- <div class="paragraph">
- <p>After that’s done, please go to our <a
href="https://github.com/apache/incubator-training";>GitHub site</a> and create
a so-called <code>Fork</code>.</p>
- </div>
- <div class="imageblock">
- <div class="content">
- <img src="../images/contributing-github-fork.png" alt="contributing
github fork" class="img-responsive">
- </div>
- </div>
- <div class="paragraph">
- <p>What happens now, is that GitHub creates a full copy of the Apache
Training repo in your account. Only you can commit to this.</p>
- </div>
- <div class="paragraph">
- <p>Now ideally you check-out your cloned repository:</p>
- </div>
- <div class="literalblock">
- <div class="content">
- <pre>git clone
https://github.com/{your-user-id}/incubator-training.git</pre>
- </div>
- </div>
- <div class="paragraph">
- <p>Now you have a copy of Apache Training on your computer and you can
change whatever you want and as it’s your copy, you can even commit these
changes without any danger of breaking things.</p>
+ <p>If nothing catches your eye and you come up with something that you
want to work on by yourself, please do share your intent by either posting on
the mailing list or creating an issue, as this allows us to limit duplication
of effort as much as possible.</p>
</div>
+ </div>
+ <div class="sect2">
+ <h3 id="_toc_code_contributions1">Code Contributions</h3>
<div class="paragraph">
- <p>As soon as you’re finished with your changes and want us to have a
look, it’s time to create a so-called <code>Pull-Request</code>.</p>
+ <p>Many of the actions listed above will take the form of contributions to
the git repository, for which we have defined a few basic guidelines to ensure
we can all collaborate effectively. Code contributions can take two forms, you
can either create a pull request on GitHub or directly attach patch files to a
Jira issue for review.</p>
</div>
<div class="paragraph">
- <p>You do that by going to your forked repository page on GitHub.</p>
+ <p>A Jira ticket and a pull request are not mutually exclusive, and we
encourage people to create both, first a Jira to discuss the issue, task,
improvement in general and later on a pull request for actual implementation
discussions. If you follow this process, please prefix the name of your pull
request with the Jira issue number, this will ensure that they automatically
get linked. If, for example, you open a pull request to fix issue TRAINING-123,
then your PR title could read "< [...]
</div>
<div class="paragraph">
- <p>Every forked repository has an additional button called "New Pull
Request":</p>
+ <p>If you are not familiar with git, how to create pull requests and
similar workflows, below is a list of useful links that should help you get
started. However as with all other things, please do reach out to us on the
mailing list if anything is unclear and you need help, we are more than happy
to help!</p>
</div>
- <div class="imageblock">
- <div class="content">
- <img src="../images/contributing-github-create-pull-request.png"
alt="contributing github create pull request" class="img-responsive">
- </div>
- </div>
- <div class="paragraph">
- <p>If you click on this, we will receive a notification on your changes
and can review them. We also can discuss your changes and have you perfect your
pull request before we accept and merge it into Apache Training.</p>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="https://help.github.com/en/articles/fork-a-repo";>Forking
a repository</a></p> </li>
+ <li> <p><a
href="https://help.github.com/en/articles/about-branches";>About
branches</a></p> </li>
+ <li> <p><a
href="https://help.github.com/en/articles/about-pull-requests";>About pull
requests</a></p> </li>
+ <li> <p><a href="https://lab.github.com/";>Github Learning Lab</a></p>
</li>
+ </ul>
</div>
<div class="sect3">
- <h4 id="_toc_keeping_your_fork_up_to_date1">Keeping your fork up to
date</h4>
- <div class="paragraph">
- <p>As we are continuously working on Training and you created a copy of
our repo, this will become out-of-date pretty soon.</p>
- </div>
- <div class="paragraph">
- <p>In order to get the changes we introduced in the official repo you
have to tell git about that.</p>
- </div>
- <div class="paragraph">
- <p>You do this locally by adding a new so-called <code>remote</code>. Per
default, the remote you cloned from is called <code>origin</code>.</p>
- </div>
- <div class="paragraph">
- <p>Usually you will call the second remote <code>upstream</code> but in
general, you can call it whatever you like.</p>
- </div>
+ <h4 id="_toc_review_process1">Review Process</h4>
<div class="paragraph">
- <p>Add the remote on the command line (or your git gui of choice):</p>
- </div>
- <div class="literalblock">
- <div class="content">
- <pre>git remote add upstream
https://github.com/apache/incubator-training.git</pre>
- </div>
+ <p>The Training project follows a review-then-commit workflow, which
basically means that no commit should be made to the repository that has not
been reviewed and approved by the required number of persons.</p>
</div>
<div class="paragraph">
- <p>If you list all your remotes, with the following command:</p>
- </div>
- <div class="literalblock">
- <div class="content">
- <pre>git remote -v</pre>
- </div>
- </div>
- <div class="paragraph">
- <p>It should output something like this:</p>
- </div>
- <div class="literalblock">
- <div class="content">
- <pre>origin https://github.com/{your-user-id}/incubator-training.git
(fetch)
-origin https://github.com/{your-user-id}/incubator-training.git (push)
-upstream https://github.com/apache/incubator-training.git (fetch)
-upstream https://github.com/apache/incubator-training.git (push)</pre>
- </div>
+ <p>For reviews we distinguish between <em>content</em> commits that add
content to training decks and <em>functional</em> commits like code changes to
tools or similar things.</p>
</div>
<div class="paragraph">
- <p>If that’s so, you’re fine to continue, if not … well, you could ask
for assistance on our dev-list.</p>
+ <p><strong>Code Commits</strong> require one approving review. This
review has to be done by a committer if the pull request was created by a
non-committer. If a committer creates a pull request and explicitly requests a
review from a non-committer, then this review is sufficient.</p>
</div>
<div class="paragraph">
- <p>In order to get all changes in our upstream-repository, just execute
the following command:</p>
- </div>
- <div class="literalblock">
- <div class="content">
- <pre>git pull upstream</pre>
- </div>
- </div>
- <div class="paragraph">
- <p>This will get all changed from upstream and merge them locally. In
order to update your GitHub version, you have to push things back to
<code>origin</code>. You can do this by executing the following command:</p>
- </div>
- <div class="literalblock">
- <div class="content">
- <pre>git push</pre>
- </div>
+ <p><strong>Content Commits</strong> require one or more approving
reviews. As we do not expect to initially have committers that are also experts
in all fields for which we host content there may be a need for two reviews in
this case: one for form by a committer and one for content by someone who
considers themselves a subject matter expert. If the committer considers
themselves to be an expert on the material one review is sufficient, just like
for code commits.</p>
</div>
<div class="paragraph">
- <p>(If no remote is provided, git will use <code>origin</code> per
default)</p>
+ <p><strong>Trivial Changes</strong> Committers can, at their discretion,
decide that a change is trivial and does not need to be explicitly approved. In
this case, the pull request or Jira issue should be marked accordingly and left
open for review for at least 72 hours. After this period has passed it can be
merged without review.</p>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="_toc_bug_reports1">Bug Reports</h3>
+ <h3 id="_toc_issue_reports1">Issue Reports</h3>
<div class="paragraph">
- <p>We use <a
href="https://issues.apache.org/jira/projects/TRAINING";>JIRA</a> as our Bug
& Issue Tracker.</p>
+ <p>We use <a
href="https://issues.apache.org/jira/projects/TRAINING";>JIRA</a> as our Issue
Tracker.</p>
</div>
<div class="paragraph">
<p>Feel free to submit <code>feature requests</code>, <code>bug
reports</code>, <code>patches</code>, <code>comment on issues</code>, …</p>
