blob: c0a23607c4e691be09e9dfc26e93b3c171dcc517 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="Date-Revision-yyyymmdd" content="20140918"/>
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Submitting patches</title>
<link href="//,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="/css/custom.css" rel="stylesheet">
<link href="/highlighter/github-theme.css" rel="stylesheet">
<script src="//"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
<a href="" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="" alt="Fork me on GitHub">
<div role="navigation" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
<div id="struts-menu" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Home<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/index.html">Welcome</a></li>
<li><a href="/download.cgi">Download</a></li>
<li><a href="/releases.html">Releases</a></li>
<li><a href="/announce-2021.html">Announcements</a></li>
<li><a href="">License</a></li>
<li><a href="">Thanks!</a></li>
<li><a href="">Sponsorship</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="">Version Notes</a></li>
<li><a href="">Security Bulletins</a></li>
<li class="divider"></li>
<li><a href="/maven/project-info.html">Maven Project Info</a></li>
<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/birdseye.html">Birds Eye</a></li>
<li><a href="/primer.html">Key Technologies</a></li>
<li><a href="/kickstart.html">Kickstart FAQ</a></li>
<li><a href="">Wiki</a></li>
<li class="divider"></li>
<li><a href="/getting-started/">Getting Started</a></li>
<li><a href="/security/">Security Guide</a></li>
<li><a href="/core-developers/">Core Developers Guide</a></li>
<li><a href="/tag-developers/">Tag Developers Guide</a></li>
<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
<li><a href="/plugins/">Plugins</a></li>
<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
<li><a href="">FAQs</a></li>
<li><a href="">Plugin registry</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/youatstruts.html">You at Struts</a></li>
<li><a href="/helping.html">How to Help FAQ</a></li>
<li><a href="/dev-mail.html">Development Lists</a></li>
<li><a href="/contributors/">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/submitting-patches.html">Submitting patches</a></li>
<li><a href="/builds.html">Source Code and Builds</a></li>
<li><a href="/coding-standards.html">Coding standards</a></li>
<li><a href="">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/release-guidelines.html">Release Guidelines</a></li>
<li><a href="/bylaws.html">PMC Charter</a></li>
<li><a href="/volunteers.html">Volunteers</a></li>
<li><a href="">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
<li class="apache"><a href=""><img src="/img/apache.png"></a></li>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="" title="Edit this page on GitHub">Edit on GitHub</a>
<h1 class="no_toc" id="submitting-patches">Submitting patches</h1>
<ul id="markdown-toc">
<li><a href="#committers" id="markdown-toc-committers">Committers</a></li>
<li><a href="#non-committers" id="markdown-toc-non-committers">Non-committers</a></li>
<li><a href="#security-patches" id="markdown-toc-security-patches">Security patches</a></li>
<li><a href="#contributing-with-github" id="markdown-toc-contributing-with-github">Contributing with GitHub</a> <ul>
<li><a href="#how-to-merge-pull-requests" id="markdown-toc-how-to-merge-pull-requests">How to merge Pull Requests</a></li>
<li><a href="#further-reading" id="markdown-toc-further-reading">Further reading</a></li>
<li><a href="#googles-patch-reward-program" id="markdown-toc-googles-patch-reward-program">Google’s Patch Reward program</a></li>
<h2 id="committers">Committers</h2>
<p>Struts uses Git so you must install a git client locally and then you can clone Struts repository:</p>
<p>either using Apache GitBox</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone
<p>or GitHub</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone
<p>and done!</p>
<p>Please remember that the <code class="highlighter-rouge">master</code> branch should be used only for small fast commits, if you are working on a large
change it is better to do it on a dedicated branch via GitHub. Please remember that pushing other branches to the repo
will replicate them to all the clones, that’s why using GitHub is a preferred way.</p>
<h2 id="non-committers">Non-committers</h2>
<p>If you aren’t a committer you can still clone the repo from Apache Gitbox but you won’t be able push any changes to it.
That’s why it is better to use GitHub</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone
<h2 id="security-patches">Security patches</h2>
<p><strong>Please read carefully, this is very important!</strong></p>
<p>If you prepared a patch to solve security issue in the Apache Struts, in the first step contact us via
<a href="">Security Mailing List</a>. <strong>Don’t publish any information about possible vulnerability</strong>.
Thus will allow us coordinate the work and review if the information about issue can be disclosed publicly.
We don’t want to inform hackers before we can protect our users :-)</p>
<p><strong>Be responsible!!!</strong></p>
<h2 id="contributing-with-github">Contributing with GitHub</h2>
<p>Using GitHub mirror is the simplest way to contribute to the Apache Struts if you are not a member
of the Struts Committers group.</p>
<p>First you must have an account created at GitHub to be able perform the next step. If you don’t,
go ahead and create one just right now! Please remember to setup
<a href="">SSH keys</a> and test them! You don’t have to use SSH Keys
and base only on user/password authentication.</p>
<p>When ready go to <a href=""></a> and click <code class="highlighter-rouge">Fork</code> button
in top right corner. This will fork the Apache Struts’ repository and will create your private (but public) repository
with the source code.</p>
<p>Next step is to clone the original repo locally</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git clone
<p>This will be an <code class="highlighter-rouge">origin</code>, you cannot push changes to the <code class="highlighter-rouge">origin</code> but don’t worry, you will use your fork.</p>
<p>Now is time to add your fork as a remote</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git remote add fork
<p>Right now you should have two remotes defined for the repo, <code class="highlighter-rouge">origin</code> and <code class="highlighter-rouge">fork</code>, use below command to confirm that</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git remote -v
<p>Now you are ready to work with the Apache Struts’ code base. Start with switching to <code class="highlighter-rouge">master</code> branch (if not already on it)</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git checkout master
<p>now is time to fetch any changes from remote repository</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git fetch
git pull
<p>you should create a branch to keep your changes and it must be done off the <code class="highlighter-rouge">master</code> branch</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git checkout -b my-branch
<p>Do your changes and commit them to <code class="highlighter-rouge">my-branch</code>, when you’re done you can push the changes to GitHub, to your fork.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git push -u fork my-branch
<p>If you still need to change something, please remember to commit and push changes, but this time you can use just</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git push
<p>as <code class="highlighter-rouge">my-branch</code> was already connected with the remote branch.</p>
<p>The final step is to open a Pull Request (short: PR) against the original Apache Struts repo. Go to the
<a href="">Apache Struts mirror</a>, then to <a href="">Pull request</a>
and hit <a href="">New Pull Request</a> button.</p>
<p>If not already selected, click on <code class="highlighter-rouge">compare across forks.</code> Right now you must select from the dropdowns on right
your fork and branch to compare the differences with the Apache Struts’ <code class="highlighter-rouge">master</code> branch.</p>
<p>Finally hit <code class="highlighter-rouge">Create Pull Request</code> button and you are done!</p>
<p>After your PR got accepted and merged you must clean up your local repo, please switch your current branch to <code class="highlighter-rouge">master</code></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git checkout master
<p>and fetch updates from remote</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git fetch -p
git pull
<p>and now you can delete your local branch</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git branch -d my-branch
<p>and you are ready to start working on another feature/issue.</p>
<h3 id="how-to-merge-pull-requests">How to merge Pull Requests</h3>
<p>The Apache Struts is using the Apache <a href="">Gitbox</a> - a bidirectional service to mirror repos
between Apache and GitHub.</p>
<p>First of all you must have an account on GitHub and <a href="">link it</a> to your Apache account.
After that you can directly merge PRs using GitHub’s UI.</p>
<h2 id="further-reading">Further reading</h2>
<li><a href="">Git at Apache</a></li>
<h2 id="googles-patch-reward-program">Google’s Patch Reward program</h2>
<p>During <a href="">SFHTML5</a> Google announced that they adding the Apache Struts project to
<a href="">the Google’s Security Patch Reward Program</a>.</p>
<p>What does it mean?</p>
<p>If you prepared a patch that eliminates a security vulnerability or improves existing security mechanism
you can get a bounty :-) You will find more details on
<a href="">the Google’s blog</a>
or under the link above, just to give you a quick guideline how does it work:</p>
<li>if you found a way to improve security of the framework but this isn’t a vulnerability:
<li>prepare a patch and submit it to our <a href="">JIRA</a>,
it can be a Pull Request on GitHub as well, but must reference the JIRA ticket.</li>
<li>let us know that you did something great, post a message to <a href="dev-mail.html">Struts Dev mailing list</a></li>
<li>if you found a vulnerability and prepared a patch that fixes the vulnerability:
<li>please contact us using the Security Mailing list <a href=""></a></li>
<li>keep all information in secret, do not publish any data about the vulnerability nor Proof-of-Concept, etc.</li>
<li>we will review the patch and if it’s a real great thing then we will merge it into our code base</li>
<li>just wait on official release of the Apache Struts and now you can request the reward from Google :-)</li>
<p class="alert alert-success">Please be aware that the committee is focused on awarding patches that are more significant than individual bug fixes.
It means that the contribution should have <em>demonstrable</em>, <em>significant</em>, and <em>proactive</em> impact on security.</p>
<p>If you are concerned that your patch can disclose a security vulnerability, instead of submitting it as a ticket,
send it directly to the <a href="">Struts Security team</a>. This will give us the possibility
to prepare a new release with your patch in secret.</p>
<p>Have fun and code!</p>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="">The Apache Software Foundation </a>.
All Rights Reserved.
<div class="col-md-12">
Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
trademarks of The Apache Software Foundation.
<div class="col-md-12">Logo and website design donated by <a href="">SoftwareMill</a>.</div>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, "script", "twitter-wjs");</script>
<script src="" async="async" defer="defer"></script>
<div id="fb-root"></div>
<script>(function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>