////
 * Copyright (C) 2015 Eclipse Foundation, Inc. and others. 
 * 
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 * 
 * SPDX-License-Identifier: EPL-2.0
////

[[project-resources-and-services]]
== Project Resources and Services

Open source projects at the Eclipse Foundation are _required_ to make use of certain Eclipse Foundation services:

* All project issues must be tracked in the issue tracker assigned to the project;
* Source code must be maintained in source code repositories assigned to the project (e.g. {aforgeName} {gitUrl}[Git] or {gerritUrl}[Gerrit] instance, or an organization on GitHub maintained by the Eclipse Foundation);
* All third-party content used by the project must be <<ip-third-party,tracked and approved>> for use by the Eclipse IP Team;
* Downloads must be distributed via {aForgeName} downloads server;
* Developer (committer) communication must occur in the _dev-list_ provided to the project by the Eclipse Foundation; and
* Projects must keep their <<pmi-metadata, Project Metadata>> up-to-date.

[[resources-identifers]]
=== Identifers
Project resources make use of two sorts of ids:

Short name::
The short name is used in various parts of Eclipse Foundation infrastructure (e.g. the name of the project's directory on the downloads and Git servers, and the URL for the project website). The short name may contain lowercase alphanumeric characters, dashes, and underlines; but does not contain periods.

Qualified identifier::
The project's short name is joined with the short name of the parent project(s) to form a qualified identifier (project id) for the project that is used as a key on services generated and/or maintained for the project by the Eclipse Foundation. 

For example the "{forgeName} Woolsey" project has a _short name_ of "woolsey"; its _qualified identifier_ is "technology.dash.woolsey", indicating that it is a subproject of the {aForgeName} _Dash_ Project which is itself a subproject of the {forgeName} _Technology_ Top Level Project.

[[resources-source]]
=== Source Code Management

{forgeName} projects must maintain source code in the repositories assigned to the project by the Eclipse Foundation. These official repositories must be the exclusive source of all project code delivered via the project's assigned distribution channel (e.g. the download server).

In order for the project to operate in an _open_ manner, it must be possible for potential contributors to have access to the code base in its most current form, so all ongoing development must be regularly pushed to these canonical repositories.

[[resources-commit]]
=== Git Commit Records

Git commit records are required to take a specific form. The credentials of the actual author must be used to populate the `Author` field. The author credentials must specify the author's actual (legal) name and email address. The email address used must match the email address that the Eclipse Foundation has on file for the author (case-sensitive).

The commit message is divided into three sections:

. One line (max 72 characters) summary;
. Description; and
. Footer.

.Example Git Commit Record
[source]
------------------------------------------------------------
commit d6cf52411377a039fc2906378711091a26e932cb
Author: Some Body <somebody@somewhere.com> <1>
Date:   Wed May 29 16:17:36 2013 +0200

    Bug 350686 - Hide unwanted action bar items <2>
    
    This change hides unwanted 'Link with Editor' and 
    'Customize View...' items from the local toolbar 
    and the view menu.
    
    Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7 <3>
    Also-by: Some Bodyelse <somebodyelse@nowhere.com> <4>
    Signed-off-by: Some Body <somebody@somewhere.com> <5>
------------------------------------------------------------

<1> The email address of the author must match the email address on the Eclipse Foundation Account, the name "Some Body" must be replaced by the real name of the person.
<2> Best practice: include the bug id in the commit message summary.
<3> Gerrit `Change-Id` (only when pushing to Gerrit for review).
<4> Additional authors can be added using `Also-by` or `Co-authored-by` entries, by replacing the name "Some Bodyelse" by the real name of the person
<5> Non-committers must _sign-off_ the commit, indicating that they aware of the terms by which the contribution has been provided to the project, using the same name and email address as used in the author field.

[IMPORTANT]
====
The name used in the `Author` field (and, when required, in the `Also-by` and `Signed-off-by` fields) must be the legal name of the contributor; the email address must be valid and real.
====

The _summary_ line is used in many places where Git commits are listed, ensure that this line is sensible by itself. The _description_ area should be used to provide more detail about the commit. The footer area is used for extra fields and values.

If the bug id is included in the summary line (using the form "Bug 12345 - xxx" or "[12345] xxx") Gerrit Code Review will automatically add a link in the corresponding Bugzilla record back to the Gerrit record (this, of course, only applies to commits pushed to Gerrit).

The `Change-Id` is used by <<resources-gerrit,Gerrit Code Review>> to associate new versions of a change back to its original review. This field need only be specified if the repository is managed by Gerrit.

An `Also-by` (or `Co-authored-by`) entry can be added for each additional author of a commit (one committer per entry). This might apply, for example, if a commit has been authored via pair-programming, or the commit is the result of collapsing multiple commits authored by multiple developers. To be considered valid the entry must take the form `Also-by: Name <email>`.

Commits that are provided by non-committers must have a `Signed-off-by` field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. To be considered valid the entry must take the form `Signed-off-by: Name <email>`. The non-committer must additionally have an Eclipse Foundation Account and must have a signed <<contributing-eca,Eclipse Contributor Agreement>> (ECA) on file.

[[resources-git]]
=== Git

Those projects that want to use Git on the {forgeName} forge, are assigned a directory in which they may create as many Git repositories as required. Committers may {gitRequestUrl}[open a bug] to request Eclipse Webmaster help to create a new Git repository for their project project. Alternatively, committers with shell accounts can create repositories themselves.

[subs="attributes"]
.Create a new Git repository
-----------------------------------------------------
> initrepo /gitroot/project/{namespace}.repo.name.git
-----------------------------------------------------

For consistency, the name of the repository must end with `.git`.

To set the description of the repository, use `sftp` or `scp` to copy a text file to `/gitroot/project/{namespace}.repo.name.git/description`. Git repository descriptions should be limited to a paragraph of one or two sentences.

Only project committers can push to {aForgeName} Git repository. A push that includes commits that do not conform to the required form will be rejected.

[NOTE]
==== 
Anybody can {gitUrl}[browse] {forgeName} Git repositories. Use a project's short name to quickly jump to the project's Git repositories with a URL of the form  `pass:a,c[{gitUrl}/<shortname>]` (e.g. `pass:a,c[{gitUrl}/dash]` for repositories associated with the `technology.dash` project).
====

[[resources-gerrit]]
=== Gerrit Code Review

https://www.gerritcodereview.com/[Gerrit] provides web based code review and repository management for the Git version control system. Many projects use Gerrit to reduce barriers and encourage contribution to the project. {gerritRequestUrl}[Open a bug] to request that the Eclipse Webmaster configure your Git repository for Gerrit. 

Commits may be pushed directly to the Git repository through Gerrit by a project committer (e.g. to the `master` branch).

Anybody can push to a `refs/for/*` branch for review in a Gerrit repository. A push that includes commits that do not conform to the required form will be rejected. Commits intended for review should have a {gerritUrl}/Documentation/user-changeid.html[`Change-Id`]

You can {gerritUrl}[browse {forgeName} repositories] directly on the Gerrit server.

[[resources-github]]
=== GitHub

Projects may opt to move some or all of their canonical source code repositories to an organization on GitHub that is maintained by the Eclipse Foundation. Both GitHub Issues and Wiki may also be used.

Any committer can {gitHubRequestUrl}[open a bug] to request that the Eclipse Webmaster create a new, or move an existing, Git repository into their project. The Eclipse Webmaster installs some _hooks_ onto all Eclipse project GitHub repository.

The _Committers hook_ grants designated project committers write access to the GitHub-hosted project repositories. Project committers must add their GitHub id to their <<contributing-account,Eclipse Foundation account>>, and must use the email address they provide to the Eclipse Foundation as the email address in the author credentials of all commits. 

The <<contributing-eca,Eclipse Contributor Agreement>> (ECA) hook will inspect incoming GitHub pull requests to ensure that the contributor has a valid ECA on file, and that the commit has been `Signed-off-by` as required. Project committers should only merge pull _green_ requests:

.Notification that the commit is properly structured and permissions are in place.
image::images/Github-cla-success.png[]

Since the GitHub API does not provide a means of absolutely denying a merge the hook will warn committers that the contributors have not signed a ECA or that the commit message is not correctly structured:

.Notification that there is something wrong with the commit.
image::images/Github-cla-failure.png[]

Click on the _Details_ link for more information. Committers must not merge commits unless they are absolutely certain that the contributer does have a valid ECA on file and the commit message includes the required `Signed-off-by` statement in the footer.

[NOTE]
==== 
The Eclipse Webmaster creates and maintains a mirror of all GitHub-hosted repositories on Eclipse Foundation hardware.
====

[[resources-github-access]]
==== Access to GitHub Repositories

All project committers have write access to their project's repositories on GitHub.

To gain write access to a project's GitHub repositories a developer must:

* Be <<elections-committer, elected>> as a project committer; and
* Provide their Github Id in their <<contributing-account,Eclipse Foundation Account>>.

To gain `admin` level access to their project's GitHub repositories, a project lead must {gitHubRequestUrl}[open a bug] against Community/GitHub. To be eligible to such permission level, the project must be in the mature phase and the request must be motivated; the project lead must explain why (on the bug) they need that access.

[TIP]
====
Granting `admin` level access is a relatively new feature. By providing an explanation why the access isr required, it will help the Eclipse Foundation's Webmaster team better understand requirements and guide the evolution of this feature.
====

[[resources-issues]]
=== Issue Trackers

{forgeName} projects must use an Eclipse Foundation-provided issue tracker. Project teams may opt to use either the {bugzillaUrl}[{forgeName} Bugzilla] instance or -- for projects that use <<resources-github,GitHub>> -- GitHub Issues instances associated with Eclipse Foundation-managed GitHub project repositories. 

[[resources-forums]]
=== Forums and Outbound Communication

All projects are assigned a {forumsUrl}[user forum] as a point of contact between the user and adopter communities, and the project developers.

The EMO strongly encourages the use of alternative communication channels for connecting with the community: project teams know their community and how to best connect with them.

[[resources-website]]
=== Project Websites

// Project-specific websites are only supported on the Eclipse forge.
ifeval::["{forgeName}"=="Eclipse"]
Project websites are an excellent way to connect an open source project with the community. Many projects opt to use the <<pmi,Project Management Infrastructure>> (PMI) <<pmi-project-page,project page>> as their webite.  PMI-based website URLs take the form of `pass:c,a[{forgeUrl}/projects/<projectid>]` (e.g. `pass:c,a[{forgeUrl}/projects/technology.foo]`). 

Many project teams opt to create a custom main project website: if so-desired, a project may host a website on Eclipse Foundation-hosted servers. Project website URLs generally take the form `pass:c,a[{wwwUrl}/<shortname>]` (e.g. `pass:c,a[{wwwUrl}/foo]`). Custom project website content is maintained in Git repositories hosted on Eclipse Foundation infrastructure. A background job moves content from the Git repository to the website; content pushed to the repository will appear on the live website within five minutes.

Project websites must implement the <<trademarks-website, branding guidelines for project websites>>.

[NOTE]
====
If a project website has not already been created for your project, {websiteRequestUrl}[open a bug] to request that the Eclipse Webmaster create one.
====
endif::[]
ifeval::["{forgeName}"!="Eclipse"]
The <<pmi,Project Management Infrastructure>> (PMI) provides the main <<pmi-project-page,project website>>. Website URLs take the form of `pass:c,a[{forgeUrl}/projects/<projectid>]` (e.g. `pass:c,a[{forgeUrl}/projects/technology.foo]`).
endif::[]

Websites _not_ hosted by the Eclipse Foundation are considered <<trademark-external-community,community portals>> and are subject to the {trademarkGuidelinesUrl}[Eclipse Foundation Trademark Usage Guidelines] (the Eclipse Foundation asserts ownership of all project name trademarks).

[[resources-builds]]
=== Builds

Use of Eclipse Foundation-provided and hosted build services, the so-called {cbiUrl}[Common Build Infrastructure] (CBI) is strongly recommended, but not strictly required. 

Whether or not a project chooses to make use of provided build resources, it must be possible for members of the community to build project artifacts from source code with reasonable effort.

[[resources-signing]]
=== Signed Artifacts

Where technically sensible, all downloadable artifacts should be {jarSigningUrl}[signed] by an Eclipse Foundation certificate.

[[resources-downloads]]
=== Downloads

The project is allocated space on the {forgeName} download and archive servers.

Project artifacts (e.g. downloads) can be distributed via third-party services (e.g. Maven Central), but -- where technically sensible -- the Eclipse Foundation-provided infrastructure must be considered the primary source of project downloads.

Project committers can {downloadsUrl}[upload project artifacts] to the project's directory on the download server. The short name is used to denote the area available to the project (e.g. `pass:a[{downloadsHost}/dash]` for the `technology.dash` project) via SFTP or SCP, or from a <<resources-builds,Eclipse Foundation hosted build infrastructure>>.

[[resources-external]]
=== External Resources

Project teams may use services that are not hosted by the Eclipse Foundation (e.g. <<resources-github,GitHub>> or <<resources-dockerhub,DockerHub>>).

The following rules apply:

* The Eclipse Foundation's <<trademarks,branding rules>> must be observed;
* External services must not add legal terms or conditions that invalidate the project licenses or copyrights;
* One or more project *committers* must have ownership rights; and
* The usual level playing field must be observed.

Even when using services not hosted by the Eclipse Foundation, project teams are required to operate in an open, transparent, meritocratic, and vendor-neutral manner. Use of the service must not add an unreasonable access barrier for contributors, and no single individual or company can exert exclusive control of the service. Administrative level control of the service must be shared by as diverse a subset of the project committers as possible, and a documented policy must be established for managing that control.

All services require that users conform to some sort of terms of use that likely dictate copyright and licensing terms. Project leads must take care to ensure that those terms of use are not at odds with the project license or impact the copyright ownership of project contributions.

[WARNING]
====
<<resources-source,Source code>>, documentation, <<resources-issues,issues/tickets/bug reports>> must all be maintained using resources that are provided and managed by the Eclipse Foundation.
====

External resources can be used for:

* User forum discussions, presentations;
* Builds and alternative sources for <<resources-downloads,downloads>>; 
* Container image management (e.g. <<resources-dockerhub,DockerHub>>); and
* Examples, blogs, social media handles.

This list is not exhaustive. Project leads should work with their PMC and the EMO to determine the terms and conditions for an external resource are compatible with the project license(s), the {ipPolicyUrl}[Eclipse IP Policy], and {edpLink}.

[[resources-dockerhub]]
==== DockerHub

The Eclipse Foundation owns several organizations on DockerHub, including https://hub.docker.com/u/eclipse/[eclipse], https://hub.docker.com/u/locationtech/[locationtech], and https://hub.docker.com/u/polarsys/[polarsys], but does not formally support or strictly manage the use of these organizations. 

For more information, please see https://wiki.eclipse.org/CBI#Docker_Hub[CBI/DockerHub] in the Eclipse wiki.

[NOTE]
====
Content distributed via official Eclipse Foundation channels must be complete enough that a consumer can (with reasonable effort) use it without needing the DockerHub distribution. That is, the DockerHub distribution needs to be considered a convenient way to leverage the content, not the only way. Please make sure that you treat any links or related discussion that you have on an Eclipse Foundation property about images distributed via DockerHub as an unofficial channel.
====

Subject to the <<resources-external,rules for the use of external resources>>, a project team can create and maintain their own organization on DockerHub. The organization name must follow the pattern `{forgeMachineName}-<shortname>` (e.g. `{forgeMachineName}-woolsey`) or some variation (e.g. `{forgeMachineName}woolsey`). As indicated in the rules, ownership of the organization must be shared by a subset of project *committers* and the project must have a documented policy regarding how access to that organization is managed.

Additionally, a PMC may decide to create and manage an organization for the Top-Level Project. The PMC may have their own policy regarding the use of DockerHub. Project teams should consult with their PMC to determine which approach is best suited for the project.

[[resources-maven]]
==== Maven Central

The Eclipse Foundation has no formal relationship with Maven Central or staging providers like OSSRH. Eclipse project teams are, however, welcome to use these services as a distribution channel.

By convention, the `groupid` should be of the form `pass:a,c[{namespace}.<shortname>]` (e.g. `{namespace}.dash` for the `technology.dash` project). Project teams should work with their PMC if some exception to this convention is required (and take care to avoid infringing on the namespaces of other projects). The form of the `artifactid` should be determined by the project team. The version number should follow the standard Semantic Versioning pattern. All pre-release builds must be appropriately labeled (e.g. `1.0M3` for pre-release builds of version `1.0`). 

Project teams must engage in the <<release>> process before labeling any software as a release version.

The Eclipse Release Engineering Team has provided some help regarding the use of Maven Central in the https://wiki.eclipse.org/IT_Infrastructure_Doc#Publish_to_Maven_Central[Eclipsepedia Wiki].

[[resources-faq]]
=== Frequently Asked Questions

[qanda]
Can a project use the _gh-pages_ support from Github to host at `<project>.github.io`?::

The project's primary website must be hosted on Eclipse Foundation infrastructure. GitHub's _gh-pages_ support can be used to host supplementary content only as a <<trademark-external-community,Community Portal>> (and is subject to the branding requirements).

Can we use GitHub for our project website? ::

The process that publishes website content pulls from the project's designated _website_ repository on `git.{forgeMachineName}.org`. A project team can put website source in a GitHub repository, but in order to actually get it on the website, some sort of process must set something up to push it to the website repository. <<resources-builds, Build infrastructure>> can be used for this.

Do we have to use the Eclipse Foundation-provided download server? ::

If you provide content to your community via any form of click-to-download notion, then the Eclipse Foundation-provided download server *must* be the primary source of that content. If, however, the concept of a download doesn't make sense for the sort of content that your project provides (e.g. your community consumes your context exclusively through Maven Central, or if source code is the only content delivered by the project), then you aren't required to provide that content via the download server. 

Can we host pre-release software (e.g. milestone builds) on Maven Central? ::

Reasonable steps must be taken to ensure that the consumer understands the pre-release nature of software. At a minimum, pre-release software must be labeled as such. A milestone build for version 1.0, for example, must be labeled as "1.0M1" (or similar). Pre-release software can be pushed to Maven Central, but due to the permanent nature of content that is pushed there, it will persist there indefinitely. Whether or not this is desirable is a decision that the project team should make with help from their PMC.

Can we use external services like OSSRH to stage pre-release builds? ::

Yes.

Can an {aForgeName} project accept anonymous code contributions? ::

No. All contributions must be associated with their author using their legal name and a real email address. In pragmatic terms, the contributor must provide their legal name and email address in the Git commit's `Author` field, and sign-off the commit using those same credentials; the contributor must also have electronically signed the ECA using those same credentials.