Skip to content

Modernize and improve the README.md and the CONTRIBUTING.md #402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merks merged 1 commit into from
Jan 4, 2026
Merged

Modernize and improve the README.md and the CONTRIBUTING.md #402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 35 additions & 61 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,52 @@
Contributing to the Eclipse Packaging Project (EPP)
===================================================
# Contributing to the Eclipse Packaging Project (EPP)

Thanks for your interest in this project. Contributions to the [Eclipse Packaging Project (EPP)] [1] are most welcome. There are many ways to contribute, from entering high quality bug reports, to contributing code or documentation changes.
Thanks for your interest in this project.
Contributions to the [Eclipse Packaging Project](https://projects.eclipse.org/projects/technology.packaging) are most welcome.
There are many ways to contribute, from entering high-quality issue reports, to contributing code or documentation changes.

Project description:
--------------------

The objectives of the Eclipse Packaging project are to

- create *entry level downloads* based on defined user profiles for the [Eclipse Simultaneous Release] [2]. The project defined and created the EPP downloads of Java Developer, Enterprise Java Developer, C/C++ Developer, RCP Developer, and more. These downloads are available from the main [Eclipse download page] [3].
- provide a platform that allows the creation of packages (zip/tar/dmg downloads) from an p2 repository. The core technology of the project enables the creation of download packages that are created by bundling Eclipse features from one or multiple Eclipse p2 repositories.

For more information, please go to the [Eclipse Packaging Project overview page] [4] or to the [EPP web site] [1].


Developer resources:
--------------------

Information regarding source code management, builds, coding standards, and more.

- <https://projects.eclipse.org/projects/technology.packaging/developer>

- Nightly builds are created on the project's Jenkins instance at <https://ci.eclipse.org/packaging/>.
- For instructions on how to run a build locally, follow the instructions of the README included in the root of this Git repository.

Create an Eclipse Development Environment
-----------------------------------------
## Create an Eclipse Development Environment

[![Create Eclipse Development Environment for EPP](https://download.eclipse.org/oomph/www/setups/svg/EPP.svg)](https://www.eclipse.org/setups/installer/?url=https://raw.githubusercontent.com/eclipse-packaging/packages/master/releng/org.eclipse.epp.config/oomph/EPPConfiguration.setup&show=true "Click to open Eclipse-Installer Auto Launch or drag onto your running installer's title area")

Contributor License Agreement:
------------------------------

Before your contribution can be accepted by the project, you need to create and electronically sign the Eclipse Foundation Contributor License Agreement (CLA).

- <http://www.eclipse.org/legal/CLA.php>

Contact:
--------

Contact the project developers via the project's "dev" mailing list.

- <https://dev.eclipse.org/mailman/listinfo/epp-dev>

Search for bugs:
----------------

This project uses Bugzilla to track ongoing development and issues.

- <https://bugs.eclipse.org/bugs/buglist.cgi?product=EPP>
## Developer Resources

Create a new bug:
-----------------
For instructions on how to run a build locally, follow the instructions of the [README.md](README.md#build-locally).

Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!
# Eclipse Contributor Agreement

- <https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EPP>
Before your contribution can be accepted by the project, you need to create and electronically sign the Eclipse Contributor Agreement:

- [https://www.eclipse.org/legal/eca/](https://www.eclipse.org/legal/eca/)

EPP Committer and Maintainer Policy
-----------------------------------
## Contact

In EPP, the "maintainer" of a package is a committer in EPP. Partially so they can do work on their package, and also so that can participate in project discussions and decisions that effect the project or whole set of EPP packages.
Please ask questions via [discussions](https://github.com/eclipse-packaging/packages/discussions).

Historical note 1: in 2010, the current set of committers were "seeded" by making all current maintainers committers. Prior to that, there was only one active committer, the Project Lead, Markus Knauer, which was less than ideal for many reasons. Now that time has passed, it was thought best to document the EPP project's policy on making new people committers and maintainers of packages (either new packages, or transfer "ownership" of an existing package). In particular, it was decided to follow "the Orbit model" of committership and package "owner".
## Issues

Historical note 2: this policy used to live on the wiki and was moved to the git repo from: https://wiki.eclipse.org/EPP/EPP_Committer_and_Maintainer_Policy
This project uses [GitHub issues](https://github.com/eclipse-packaging/packages/discussions) to track ongoing development and issues.
Be sure to search for existing bugs before you create another one.
Contributions are always welcome!

If someone is a committer on another Eclipse project, and they state they are interested in contributing and maintaining an EPP package (or, transferring ownership of an existing EPP package), that history with other Eclipse projects suffices for them to be nominated and voted-in as a committer. This differs from most other projects where, for good reason, a person must (usually) have a history of contributions to that specific project, not just Eclipse in general. There still could be reasons an existing committer would note "no" (-1) for a nomination, for example, "no, I am the current maintainer and I do not agree to this!" ... or some other fairly large issue. Normally people do not vote "0" just because they have no first hand knowledge of a person's committer history (as they might on other projects), but vote "+1" if basic criteria are met, to be welcoming and supportive of new people coming in.
## EPP Committer and Maintainer Policy

Normally, as with most other Eclipse projects, unless a committer explicitly "resigns" there would be no automatic removal of a committer just because package responsibility is transferred, except eventually the usual "inactive" reasons would apply ... if someone is no longer responsible for maintaining a package and has not been active on mailing lists, etc., for a period of 6 months or so, the Project Lead can remove them via Eclipse Portal for "inactivity". And, of course, committers should explicitly resign, when appropriate, such as they are changing responsibilities and know they have no interest or time to be involved.
For each EPP package,
there is a commiter who is the package _maintainer_.
The maintainer is expected to participate in overall project discussions and to be involved in making decisions that affect the maintained package.

If someone is a committer on another Eclipse project,
and they state they are interested in contributing and maintaining an EPP package
or, transferring ownership of an existing EPP package,
that history with other Eclipse projects suffices for them to be nominated and voted-in as a committer.
This differs from most other projects where, for good reason, a person must (usually) have a history of contributions to that specific project, not just Eclipse in general.
There still could be reasons an existing committer would note "no" (-1) for a nomination,
for example, "no, I am the current maintainer and I do not agree to this!"
Normally people do not vote "0" just because they have no first hand knowledge of a person's committer history (as they might on other projects),
but vote "+1" if basic criteria are met, to be welcoming and supportive of new people coming in.

[1]: http://eclipse.org/epp/
[2]: https://github.com/eclipse-simrel/.github/blob/main/wiki/Simultaneous_Release.md
[3]: https://www.eclipse.org/downloads/eclipse-packages/
[4]: https://projects.eclipse.org/projects/technology.packaging
Normally, as with most other Eclipse projects,
unless a committer explicitly "resigns" there would be no automatic removal of a committer just because package responsibility is transferred,
except eventually the usual "inactive" reasons would apply.
If someone is no longer responsible for maintaining a package and has not been active on mailing lists, issues, or discussions for a period of roughly six months,
the Project Lead can remove them via Eclipse Portal for "inactivity".
And, of course, committers should explicitly resign, when appropriate, such as when they are changing responsibilities and know they have no interest or time to be involved.
116 changes: 58 additions & 58 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,90 +1,90 @@
# The EPP Build

The [Eclipse Packaging Project (EPP)](https://projects.eclipse.org/projects/technology.packaging/) provides the download packages based on the content of the yearly Simultaneous Release.
The download packages are provided from [www.eclipse.org/downloads/eclipse-packages/](https://www.eclipse.org/downloads/eclipse-packages/).
The [Eclipse Packaging Project (EPP)](https://projects.eclipse.org/projects/technology.packaging/) provides the download packages based on the content of the quaterly Simultaneous Release.
The download packages are avaiable at [https://www.eclipse.org/downloads/eclipse-packages/](https://www.eclipse.org/downloads/eclipse-packages/).

## Creating and releasing packages
## Creating and Releasing Packages

Please see [RELEASING.md](RELEASING.md) in this repo for instructions on the release process for the EPP project.
Please see [RELEASING.md](RELEASING.md) for instructions on the release process for the EPP project.

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to setup an environment for contributing to the EPP project.

## Build Locally

It's _easy_ to run the build locally! All you need is Maven:
It's _easy_ to run the build locally!
All you need is Maven:

mvn clean verify

will build all the packages (using automatically activated profiles) and the resulting zip/tar/dmg will be in `packages/org.eclipse.epp.package.${PACKAGE}.product/target/products`.
In addition the combined p2 site will be in `archive/repository`.
This will build all the packages (using automatically activated profiles) and the resulting `zip`, `tar.gz`, and `dmg` will be in `packages/org.eclipse.epp.package.${PACKAGE}.product/target/products`.
In addition, the combined p2 site will be in `archive/repository`.

### Build a single package
### Build a Single Package

If you want to build just a single package add the profile for the package you want to build, along with the profile to materialize the product:
If you want to build just a single package, add the profile for the package you want to build, along with the profile to materialize the product:

mvn verify -Pepp.p2.common -Pepp.product.cpp -Pepp.p2.cpp -Pepp.materialize-products

This build creates output in two places:

1. tar.gz/zip/dmg archives with the packages in `archive/` and
2. a p2 repository with the EPP artifacts in `archive/repository/`.

### Build a single platform
1. The `zip`, `tar.gz`, and `dmg` archives for the packages in `archive/`.
2. The p2 repository with the EPP artifacts in `archive/repository/`.

By default the maven build runs the build for all platforms, this can be time consuming and can be changed to only build a limited number of platforms, a useful thing to do for testing changes locally.
There is no profile (PRs welcome!) to disabled other platforms, instead modify `releng/org.eclipse.epp.config/parent/pom.xml` to exclude the unwanted platforms in `target-platform-configuration`'s configuration.
### Build a Single Platform

### Windows users

In the past the last step in the build process used to fail.
For further details see [bug 426416](https://bugs.eclipse.org/bugs/show_bug.cgi?id=426416).
If that happens again you can omit the `verify` stage and simply `package`.

mvn clean package -Pepp.package.rcp -Pepp.materialize-products
By default the maven build runs the build for all platforms.
This can be time consuming and can be changed to only build a limited number of platforms
which is a useful for testing changes locally.
There is no profile (PRs welcome!) to disable other platforms.
Instead modify `releng/org.eclipse.epp.config/parent/pom.xml` to exclude the unwanted platforms in `target-platform-configuration`'s configuration.

### Available Profiles

Each package uses its own profile, with the zip/tar/dmg in `packages/org.eclipse.epp.package.${PACKAGE}.product/target/products`.
With the `epp.materialize-products` profile the zip/tar/dmg will be created, otherwise only the p2 site will be created.

- epp.package.committers
- epp.package.cpp
- epp.package.embedcpp
- epp.package.dsl
- epp.package.java
- epp.package.jee
- epp.package.modeling
- epp.package.php
- epp.package.rcp
- epp.package.scout

macOS dmg files can only be created within the Eclipse Foundation network. To enable creating
dmg files enable the `eclipse-package-dmg` profile. Without `eclipse-package-dmg` enabled, the .tar.gz
for macOS will be created regardless.

With the signing profiles enabled, the build artifacts (bundles, features) and the
Windows and macOS executables are signed. This is done by using the Eclipse Foundation
internal signing service and can be activated only if the build is running there.

- `eclipse-sign-jar` profile enables signing of the EPP bundles and jar files
- `eclipse-sign-mac` profile enables usage of macOS signing service
- `eclipse-sign-dmg` profile enables signing of the DMG files for the macOS platform (the `eclipse-package-dmg` needs to be enabled too!)
- `eclipse-sign-windows` profile enables usage of Windows signing service
Each package uses its own profile, with the resulting `zip`, `tar.gz`, and `dmg` in `packages/org.eclipse.epp.package.${PACKAGE}.product/target/products`.
With the `epp.materialize-products` profile the `zip`, `tar.gz`, and `dmg` will be created, otherwise only the p2 site will be created.

- `epp.package.committers`
- `epp.package.cpp`
- `epp.package.embedcpp`
- `epp.package.dsl`
- `epp.package.java`
- `epp.package.jee`
- `epp.package.modeling`
- `epp.package.php`
- `epp.package.rcp`
- `epp.package.scout`

The macOS `dmg` files can only be created within the Eclipse Foundation infrastructure.
To enable creating `dmg` files enable the `eclipse-package-dmg` profile.
Without `eclipse-package-dmg` enabled, only the `tar.gz` for macOS;
it will always be created regardless of the profile.

With the signing profiles enabled, the build artifacts, i.e., bundles and features,
and the Windows and macOS executables are signed.
This is done by using the Eclipse Foundation internal signing service and can be activated only if the build is running there.

- The `eclipse-sign-jar` profile enables signing of the EPP bundles and jar files.
- The `eclipse-sign-mac` profile enables usage of macOS signing service.
- The `eclipse-sign-dmg` profile enables signing of the DMG files for the macOS platform; `eclipse-package-dmg` profile needs to be enabled too.
- The `eclipse-sign-windows` profile enables usage of Windows signing service.

### Additional Configuration Possibilities

By default, the EPP build uses the content of the Eclipse Simultaneous Release _Staging_
repository at <https://download.eclipse.org/staging/2026-03/> as input. Sometimes it is
desired to build against another release (e.g., a different milestone), or against a local
mirror of this repository. This can be achieved by setting the Java property
`eclipse.simultaneous.release.repository`to another URL. As an example, by adding the
following argument to the Maven command line, the EPP build will read its input from the
composite Eclipse 2026-03 repository:
By default, the EPP build uses the content of the Eclipse Simultaneous Release _Staging_ repository at <https://download.eclipse.org/staging/2026-03/> as input.
Sometimes it is desired to build against another release, e.g., a different milestone,
or against a local mirror of this repository.
This can be achieved by setting the Java property `eclipse.simultaneous.release.repository` to another URL.
As an example, by adding the following argument to the Maven command line,
the EPP build will read its input from the composite Eclipse 2026-03 repository:

-Declipse.simultaneous.release.repository="https://download.eclipse.org/releases/2026-03"

### EPP Configuration File format

The individual EPP packages have a special file called epp.website.xml that defines various
pieces of information about the package. The format of the file is:
The individual EPP packages have a special file called `epp.website.xml` that specifies various details about the package.
The format of the file is as follows:

```
<?xml version="1.0" encoding="UTF-8"?>
Expand Down Expand Up @@ -117,4 +117,4 @@ pieces of information about the package. The format of the file is:
...

</configuration>
```
```
Loading
Loading