Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Nebula/Contributions/New Widgets"

(Move from gerrit/Eclipse git server to PRs and GitHub)
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
===If you want to add a new widget to Nebula, please work with the project lead to get the initial contribution in. After this is done, the general process is described below.===
+
<big>'''If you want to add a new widget to Nebula, please work with the project lead to get the initial contribution in. After this is done, the general process is described below.'''</big>
 +
<br/>
  
  
Line 12: Line 13:
  
 
* [https://dev.eclipse.org/site_login/createaccount.php Create an Eclipse Account] (or use your existing one)
 
* [https://dev.eclipse.org/site_login/createaccount.php Create an Eclipse Account] (or use your existing one)
* [http://wiki.eclipse.org/Development_Resources/Contributing_via_Git#Eclipse_Foundation_Contributor_License_Agreement Sign the CLA]
+
* [https://wiki.eclipse.org/Development_Resources/Contributing_via_Git#Eclipse_Contributor_Agreement Sign the ECA]
  
Once the account has been created and the CLA is signed, you need to file a bug against Nebula Core.  
+
Once the account has been created and the ECA is signed, you need to file a bug against Nebula Core.  
  
 
Here are some example bugs of previous contributions:
 
Here are some example bugs of previous contributions:
Line 54: Line 55:
  
 
== Organize your Code ==
 
== Organize your Code ==
You will get your own personal slot in the Nebula git repository.your [http://git.eclipse.org/c/nebula/org.eclipse.nebula.git/tree/widgets component will be included into this folder]. A [https://github.com/eclipse/nebula/tree/master/widgets GitHub mirror] exists, but it cannot be used for pushing. It is also possible to become a sub project of the greater Nebula. You will then operate semi-independent from Nebula and take care of your own builds and repository.  
+
You will get your own personal slot in the Nebula git repository. Your [https://github.com/eclipse/nebula/tree/master/widgets component will be included into this folder]. It is also possible to become a sub project of the greater Nebula. You will then operate semi-independent from Nebula and take care of your own builds and repository.  
  
 
If you are not your own sub project then you will first start in the Nebula incubation area. You will need to provide several components to become part of the Nebula code.  
 
If you are not your own sub project then you will first start in the Nebula incubation area. You will need to provide several components to become part of the Nebula code.  
Line 75: Line 76:
  
 
* [[Git|All you need to know about git]]
 
* [[Git|All you need to know about git]]
* [http://git.eclipse.org/c/nebula/org.eclipse.nebula.git All eclipse git repositories (get your ssh link here)]
+
* [https://github.com/eclipse/nebula Nebula git repository]
  
 
== Provide Build information ==
 
== Provide Build information ==
Line 84: Line 85:
 
Here are the links to our current build jobs:
 
Here are the links to our current build jobs:
  
* https://hudson.eclipse.org/hudson/job/nebula.nebula/
+
* https://ci.eclipse.org/hudson/job/nebula.nebula/
* https://hudson.eclipse.org/hudson/job/nebula.incubation/
+
* https://ci.eclipse.org/hudson/job/nebula.incubation/
  
 
Once you are a committer you have access to the build configuration.
 
Once you are a committer you have access to the build configuration.

Latest revision as of 10:14, 6 August 2018

If you want to add a new widget to Nebula, please work with the project lead to get the initial contribution in. After this is done, the general process is described below.



Widget Vote

As soon as the contribution becomes serious, the lead will start a vote for the new contribution. This is an internal procedure for the Nebula project. The vote period is one week. For the vote to pass, we require no (0) -1's. Everybody can express their opinion but only committer votes count. The vote will be done through the nebula-dev mailing list.

File a bug to request your contribution

You will be instructed the project lead to file a bug against Nebula core in bugzilla. Before you can do that, you need to get an Eclipse account.

Once the account has been created and the ECA is signed, you need to file a bug against Nebula Core.

Here are some example bugs of previous contributions:

You need to include the source code and additional resources like images and stuff like that (one or more plug-in projects) as an attachement. Only the code that you own and have the copyright. Each source member needs to have the standard EPL header like you see in every Eclipse source. Do not include any third party code. Do not include any zip files in the projects. Just your sources and other resources. You can include some additional information like links to the working product or links to screenshots.

Ready? File a bug against Nebula/Core.

Provide Legal Information

If your code is to be distributed from Eclipse, we need to you comply to some legal rules. One of the rules is the inclusion of copyright notices in source code and legal documents in features and plug-ins.

Information about this is described in A Guide to the Legal Documentation for Eclipse-Based Content which is linked from here.

We will assess your contribution

We will take a look at your code to assess the quality. If we have problems with it we will let you know on the bug. We will also do a preliminary check on any IP (Intelectual Property) issues. After this is done, the project lead will file a new bug in a separate Bugzilla system known as IPZilla. This bug is called a CQ (Contribution Questionnaire).

Here an automatic scanning of the source will take place. It will be examined on foul words, religious statements, terroristic information and all that. You will also need to declare that you have the rights to the code.

One of the Eclipse PMC members will do some magic and authorize the CQ. After this has been done, we have to wait on the Eclipse legal team to do a triage on the code and give their final OK.

Committer vote

The Nebula committer vote is normally based on meritocracy. This means that you are invited by the community to participate based on what you have done for the project. In case of a new widget contribution, the Nebula project lead deviates from this rule but proposing you as committer as soon as the code is accepted by Eclipse legal.

The voting process is a formality but you cannot have any votes against you (-1). Once you are voted in (two or more +1), you will be provided with an Eclipse committer ID by the Eclipse Webmasters.

The rationale for this process is based on the fact that there is no common code base in Nebula. All widgets are self sustained and isolated pieces of code, mostly maintained by their original contributor.

Only one committer is initially voted in. If your team consists of more than one committer then the other committers can earn their way in by providing contributions and showing their support to the Nebula project.

If you want to come on board immediately with more than one new committer, this can only be done by filing a new project.

Create a Contribution to the Example View

Nebula contains an overall Example View that provides an extension point. With this extension point you can contribute a Tab to the view that shows all the details of your widget.

All Nebula Widgets are required to contribute to this extension point in a separate bundle.

Organize your Code

You will get your own personal slot in the Nebula git repository. Your component will be included into this folder. It is also possible to become a sub project of the greater Nebula. You will then operate semi-independent from Nebula and take care of your own builds and repository.

If you are not your own sub project then you will first start in the Nebula incubation area. You will need to provide several components to become part of the Nebula code.

Lets take a look at the structure of the Oscilloscope widget.

  • org.eclipse.nebula.widgets.oscilloscope
    This is the main code of this widget. It is included in one project but your UI component can span more than one project. Please follow the namespace and discuss on the mailing list what the best name of the component can be.
  • org.eclipse.nebula.widgets.oscilloscope.example
    This is the contribution to the Example view. Every component is required to contribute to the example view. Here you can showcase your widget. Make it as fancy as possible.
  • org.eclipse.nebula.widgets.oscilloscope.feature
    The feature project that will contain only your UI component. Please take a look at the contents of other features for inspiration. Make sure to provide the correct naming and descriptions in the feature and follow the same pattern as the other features.
  • org.eclipse.nebula.widgets.oscilloscope.snippets
    This contains the snippets for your code. Snippets contain short code examples on how to use your widget. This is mandatory. See other snippet projects for some inspiration.
  • org.eclipse.nebula.widgets.oscilloscope.tests
    This contains the unit tests for your component. Obviously this is also mandatory. Please provide a code coverage of at least 80%.

Checkin your code

With your committer account you can check-in your code into git. If you are not a committer yet, this will be done for you by one of the current committers. You will need the ssh link as provided on this page. Once your code is checked in, we have to add your widget to the build. If you are comfortable with it and able to do it (committer status), see the releng section of the repository for information and add your component, otherwise drop a line on the list and we are happy to help you with it.

Provide Build information

Build and CI overview

We use tycho to build the Nebula after every commit. Please take a look at the pom.xml files in the other widgets and apply a copy and paste to your projects. Once you think your product is ready for the main stage, give the list a signal. We will then include your widget in the incubation build. It needs to stay there until it is API stable. If you break the build you break everything. So be careful with what you commit, take a keen eye on the build and fix any build errors as soon as possible.

Here are the links to our current build jobs:

Once you are a committer you have access to the build configuration.

Add your component to the build

Add poms to your folders

You will need to add pom.xml in your plugins and features. The best way to achieve that is to copy pom.xml from existing widget (beware, features, tests and bundles have different poms!). For a component myComponent, all poms will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
	xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
 
	<parent>
		<artifactId>nebula-parent</artifactId>
		<groupId>org.eclipse.nebula</groupId>
		<version>1.0.0-SNAPSHOT</version>
		<relativePath>../../../releng/org.eclipse.nebula.nebula-parent</relativePath>
	</parent>
 
	<groupId>org.eclipse.nebula</groupId>
	<artifactId>org.eclipse.nebula.widgets.myComponent.bundleName</artifactId>
	<version>0.1.0-SNAPSHOT</version>
	<packaging>One of (eclipse-test-plugin | eclipse-plugin | eclipse-feature)</packaging>
</project>

The only things to change are artifactId which must be your bundle name as defined in MANIFEST.MF, and packaging (for .examples, use eclipse-plugin).

Contribute to aggregation features and update-sites

Nebula contains aggregation features aimed to ease consumption of Nebula widgets. For all the next step, use dedicated editors in Eclipse (to avoid making mistakes), and always keep .qualifier suffix for versions. Add (assuming your new contribution gets into incubation):

  • your .example bundle to the releng/org.eclipse.nebula.incubation.examples.feature/feature.xml.
  • your .feature feature to the included features of releng/org.eclipse.nebula.incubation.feature/feature.xml.
  • your .feature feature to the releng/org.eclipse.nebula.updatesite.incubation/category.xml in category Nebula Individual Incubation Widgets

Contribute to master pom

Tell maven that you want your stuff to be built by adding to releng/org.eclipse.nebula.nebula-incubation/pom.xml <modules>...</modules> the relative path to your artifacts

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>org.eclipse.nebula</groupId>
	<artifactId>nebula-incubation</artifactId>
	<version>1.0.0-SNAPSHOT</version>
	<packaging>pom</packaging>
	<name>Nebula incubation parent</name>
	<description>Parent pom for all incubation widgets in Nebula</description>
 
	<properties>
		<tycho-version>0.13.0</tycho-version>
		<mockito-version>1.8.4</mockito-version>
		<junit-version>4.8.1</junit-version>
		<signer-input-directory>/home/data/httpd/download-staging.priv/nebula</signer-input-directory>
		<download-publish-path>/home/data/httpd/download.eclipse.org/nebula/incubation/snapshot</download-publish-path>
	</properties>
 
	<parent>
		<groupId>org.eclipse.nebula</groupId>
		<version>1.0.0-SNAPSHOT</version>
		<artifactId>nebula-parent</artifactId>
		<relativePath>../org.eclipse.nebula.nebula-parent</relativePath>
	</parent>
 
	<modules>
		<!-- Dependencies -->
		<module>../org.eclipse.nebula.nebula-parent</module>
		<module>../../examples/org.eclipse.nebula.examples</module>
		<module>../../examples/org.eclipse.nebula.examples.feature</module>
		<module>../org.eclipse.nebula.examples.incubation.feature</module>
 
		<!-- blah-blah .... -->
 
		<!--myComponent -->
		<module>../../widgets/myComponent/org.eclipse.nebula.widgets.myComponent</module>
		<module>../../widgets/myComponent/org.eclipse.nebula.widgets.myComponent.example</module>
		<module>../../widgets/myComponent/org.eclipse.nebula.widgets.myComponent.snippets</module>
		<module>../../widgets/myComponent/org.eclipse.nebula.widgets.myComponent.tests</module>
		<module>../../widgets/myComponent/org.eclipse.nebula.widgets.myComponent.feature</module>
 
		<!-- blah-blah .... -->
 
		<!-- Dist -->
		<module>../org.eclipse.nebula.updatesite.incubation</module>
		<module>../org.eclipse.nebula.incubation.feature</module>
 
	</modules>
 
</project>

Test it locally before committing

From releng/org.eclipse.nebula.nebula-incubation, run a mvn clean install. Sit down and enjoy. If it looks fine you can push.

Add Component to the Website

Once you are a committer, you are able to checkout the website. If you checkin, the new code is published within 5 minutes. How to check out the Nebula website and make changes is explained here. If you have questions please ask them on the list.

Back to the top