//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

[[cg-source]]
== Participate in the Code

If you are more interested in digging into what makes Jetty tick then this some information that you will need to arm yourself with.
First we start with how to checkout and build Jetty, then on to our general coding standards followed by the actual patch contribution process.


[[cg-community-source]]
=== Source Control

The https://github.com/eclipse/jetty.project[Eclipse Jetty project] is located at https://github.com[Github] under the Eclipse Foundation https://github.com/eclipse[parent project]. There are a number of branches that are generally of interest.

.Active Eclipse Jetty Branches
[cols="3"]
|===
| https://github.com/eclipse/jetty.project/tree/jetty-10.0.x[jetty-10.0.x] | Development Branch for Jetty 10 | Java 9+
| https://github.com/eclipse/jetty.project/tree/jetty-9.4.x[jetty-9.4.x] | Maintenance Branch for Jetty 9.4 (default branch) | Java 8
| https://github.com/eclipse/jetty.project/tree/jetty-9.3.x[jetty-9.3.x] | Maintenance Branch for Jetty 9.3 | Java 8
| https://github.com/eclipse/jetty.project/tree/jetty-8.1.x[jetty-8.1.x] | Historical Branch for Jetty 8 | Java 7
https://github.com/eclipse/jetty.project/tree/jetty-7[jetty-7] | Historical Branch for Jetty 7 | Java 6
|===

If you are planning on working with a specific issue within Jetty it is important to target the correct branch for a pull request. Pull requests that are targeted at Maintenance Branches are typically merged forward into subsequent branches while historical branches are left alone merge wise.  Depending on the nature of an issue a historical branch may have an issue cherrypicked forward, but maintenance releases are merged wholesale forward as a matter of project policy.

==== Primary SCM

The primary repository for Jetty is:

Jetty Project Repository::
  https://github.com/eclipse/jetty.project

==== Secondary SCM

These are the URLs for Jetty-related code and metadata.
These are not needed to use Jetty; these are primarily of use for developers who are working with the open source project within Eclipse.

Administrative pom.xml file::
  https://github.com/eclipse/jetty.parent
Build related artifacts that release separately, common assembly descriptors, remote resources, etc.::
  https://github.com/eclipse/jetty.toolchain
Files associated with the development of Jetty -- code styles, formatting, iplogs, etc.::
  http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git

[[t-contributing-build]]
=== Maven Build

Eclipse Jetty uses http://maven.apache.org/[Apache Maven] for managing the project metadata and controlling the build.

Building Jetty should simply be a matter of changing into the relevant directory and executing the following commands:

[source, screen, subs="{sub-order}"]
....

$ git clone https://github.com/eclipse/jetty.project.git
$ cd jetty.project
$ mvn install


....

All relevant dependencies should be downloaded into your local repository automatically and the build should proceed normally.

____
[NOTE]
Jetty has a great many test cases that run through the course of its build.  Many of these tests spin up embedded instances of Jetty itself and it is not uncommon to see hundreds or more instances of Jetty start and stop during tests.
Periodically we find some test cases to be more time dependent than they should be and this results in intermittent test failures.
You can help track these down by opening an https://github.com/eclipse/jetty.project/issues[Issue].
____



[[cg-coding-standards]]
=== Coding Standards

Jetty uses number of conventions for its source code. The developers of Jetty use a variety of tooling and editors when developing Jetty so standards and conventions are important!

==== Intelli-J

The suggested configuration for Intelli-J when working with Jetty is available here: http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/idea-jetty-codestyle-settings.jar[Intelli-J Codestyle]

==== Eclipse

The Eclipse format configuration can be found here:
http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/jetty-eclipse-java-format.xml[Eclipse Java Formatting]

There are also some templates available for Eclipse here:
http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/jetty-eclipse-codetemplates.xml[Eclipse Code Templates]

==== Code Conventions

The following is an example of the Java formatting and naming styles to apply to Jetty:

[source, java, subs="{sub-order}"]
----

import some.exact.ClassName;      // GOOD
import some.wildcard.package.*;   // BAD!

package org.always.have.a.package;

/* --------------------------------------------------------- */
/** Always have some javadoc
 */
class MyClassName
{
    // indent by 4 spaces.
    // use spaced to indent
    // The code must format OK with default tabsize of 8.

    private static final int ALL_CAPS_FOR_PUBLIC_CONSTANTS=1;

    // Field prefixed with __ for static of _ for normal fields.
    // This convention is no longer mandatory, but any given
    // class should either consistently use this style or not.
    private static String __staticField;
    private Object _privateField;


    // use getters and setters rather than public fields.
    public void setPrivateField(Object privateField)
    {
        _privateField=privateField;
    }

    public Object getPrivateField()
    {
        return _privateField;
    }

    public void doSomething()
        throws SomeException
    {
        Object local_variable = _privateField;
        if (local_variable==null)
        {
             // do Something
        }
    }
}

----

While Eclipse Jetty is an open source project it is also a member of the Eclipse Foundation which carries along some additional responsibilities.
Intellectual Property is a hallmark concern of the Eclipse Foundation so you are encouraged to understand what that entails before diving in.
As much as we would like to accept a tremendous pull request, without the proper chain of events being completed our hands are tied.
That being said, the steps are not particularly onerous and we are happy to work with you to get them accomplished.


[[cg-patches]]
=== Contributing Patches

We love seeing people contribute patches to the Jetty project and the process is relatively simple.
The requirements to commit are modest but very important to the Eclipse Foundation and the intellectual property of the open source project.
The following is the general process by which we operate.

* You must have a signed Eclipse Contributor Agreement.
* This agreement must be under the _same_ email address as the Git pull request originates from.
* The commit must be signed.
* When the pull request is made, a git-hook will validate the email address.
** If the result is a green checkbox then the Jetty committers can review the pull request.
** If the result is a red X then there is absolutely nothing the Jetty committers can do to accept the commit at this point.
* This may not be the final form a commit will take, there may be some back and forth and you may be asked to re-issue a pull request.


Not everything is specifically relevant since we are at GitHub but the crux of things are detailed there.
The ECA is *critically* important to the process.

[[cg-contributing-eca]]
==== Sign an Eclipse Contributor Agreement (ECA)

The Eclipse Foundation has a strong Intellectual Property policy which tracks contributions in detail to ensure that:

1.  Did the contributor author 100% of the content?
2.  Does the contributor have the rights to contribute this content to Eclipse?
3.  Is the contribution under the project’s license(s) (e.g. EPL)

A contributor needs to e-sign a Eclipse Contributor Agreement (for more explanation see the http://www.eclipse.org/legal/ecafaq.php[Eclipse ECA FAQ] ) regardless of how their contribution patch is provided.
You can familiarize yourself with the Eclipse wiki page at http://wiki.eclipse.org/Development_Resources/Contributing_via_Git[Contributing via Git].
In order to have a pull request accepted by any Eclipse project you *must* complete this agreement.
____
[TIP]
Log into the https://www.eclipse.org[Eclipse home page] (you will need to create an account with the Eclipse Foundation if you have not already done so), click on "Eclipse ECA", and complete the form.
Be sure to use the _same email address_ when you create any Git commit records.
____

[[t-contributing-git-config]]
==== Configuring Git

GitHub has copious amounts of quality documentation on how to interact with the system and you will minimally need to configure the user.email property.
Check out the following link:https://help.github.com/articles/setting-your-email-in-git[guide on GitHub] for more information.

[[t-contributing-making-the-commit]]
==== Making the Commit

When making the commit for the pull request it is  _vital_ that you "sign-off" on the commit using `git commit -s` option.
Without this sign-off, your patch cannot be applied to the Jetty repository because it will be rejected.

You can check out the link:https://help.github.com/articles/signing-tags-using-gpg[guide at Github] for more information.
____
[TIP]
One way to think of this is that when you sign the ECA you are indicating that you are free to contribute to eclipse, but that doesn't mean everything you ever do can be contributed.
Using the commit signing mechanism indicates that your commit is under the auspices of your agreement.
____

If a pull request is for a particular issue in our repository then the format of the commit message is important.
The message should follow the form "Issue #123 <description of the commit>".
When the Jetty project runs releases we have an automated process that scans for commits with this format for inclusion in our VERSION.txt file.

[source, screen]
----
> git commit -s -m "Issue #123 resolving the issue by adding widget"
----

[[cg-the-pull-request]]
==== The Pull Request

Pull requests are very much a GitHub process so best link:https://help.github.com/articles/creating-a-pull-request[explained by Github].

[[cg-our-policies]]
==== Our Policies

We wholeheartedly welcome contributions to Jetty and will do our best to process them in a timely fashion.
While not every contribution will be accepted, our commitment is to work with interested parties on the things they care about.
With that in mind, we can only handle pull requests with actively engaged parties.
We reserve the right to abandon pull requests whose authors do no respond in a timely fashion.

We will generally adhere to the following time frames for contributions:

* Invalid Pull Requests - 1 week
** These pull requests do not follow the contribution requirements for some reason, be it missing contributor agreement or the wrong email.
** We will try and follow up with the pull request author to resolve the issue but much of this is out of our hands and are between committer and the Eclipse Foundation.
** If we do not hear from the contributor after a week we will close the pull request.

* Valid Pull Requests - 2 weeks
** These pull requests have a green check mark after the commit title.
** If the pull request can be immediately applied we will do so.
** There may need to be some conversation on the issue in which case a committer will follow up with the author in the pull request.
** If the original contributor does not respond within 2 weeks we may close the commit.
** If we see value in the commit yet the author has not responded after 2 weeks we may make some variation of the commit ourselves.
