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 "Architecture Council/Contributor Guide Recommendation"

m
(17 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<font size="+1"><b><font color="orange">Under Construction: </font>This page is still under construction. It should provide a recommendation for new projects to provide a Gontributor Guide. See {{bug|397644}} for more information.</b></font>
+
= Contributor Guide - Motivation =
 +
Having concise and clear information how to get involved in a project is very important for building the community around a project.
 +
Therefore, to simplify adoption and encourage contributions it is recommended that projects maintain a "Contributor Guide" page.
  
= How to Contribute Page - Motivation =
+
= What a Contributor Guide Should / Could Contain? =
To simplify adoption and encourage contributions it is recommended that Projects maintain a "How to Contribute Page". Such a page may contain information about:
+
Below are some hints what a contributor guide should contain.  
* the dependencies of the project
+
* how to quickly setup the workspace for local development - where/how to get the sources and import projects into the IDE, how to easily get all the necessary libraries the project depends on, etc...
+
* how to build the project artifacts (e.g. bundles, features, standalone products)
+
* some ideas what could be contributed to the project
+
* project speciffic preferences on code quality, proposing patches, etc...
+
  
Such information helps adopters to see for example all the dependencies of the project.
+
== Setting up the development environment ==
People interested in the project could easily start looking into and playing with the code, and hopefully do contributions.
+
Make it easy for people who got interested in your project to start playing with it
 +
* Provide a clear description how to get the sources in the IDE. See an [[EGit/Contributor_Guide#Obtaining Sources|example]].
 +
* Describe how to setup any additional tools needed for the development. See an [[EGit/Contributor_Guide#Development IDE Configuration|example]].
 +
* Describe what the dependencites of the project are, or even better how to easily get all the necessary libraries the project depends on. Provide for example a target platform definition (see Tools below). See an [[EGit/Contributor_Guide#Dependencies|example]].
 +
* Describe any necessary steps to build the artifacts of the project (e.g. bundles, features, standalone products). See an [[EGit/Contributor_Guide#Builds|example]].
 +
 
 +
== Contributing Code ==
 +
Make it very clear what are the steps a contributor needs to follow, so that his contribution reaches the project and may be accepted
 +
 
 +
* Include very specific instructions on how contributions are accepted. For example, if the project accept contributions via Gerrit, describe the mechanics of using Gerrit for the contribution
 +
* Indicate whether or not the project will accept GitHub pull requests. If yes, then describe the necessary steps to have the project honor those requests.
 +
* Describe the legal part of the proccess for accepting contributions, e.g. the three questions which should be answered, references to the [http://www.eclipse.org/legal/CLA.php CLA] / [http://www.eclipse.org/legal/CoO.php CoO] (both still drafts)
 +
* Provide a CONTRIBUTING file in the root of each repository
 +
** Due to the nature of Git, repositories get copied around a lot. Mirrors are hosted in various locations that may or may not have a connection back to the project website. There is an evolving standard of putting "CONTRIBUTING" file in the root of each repository
 +
** Keep the file in a "standard" location - the root of the repository. This could allow tools like the PMI to magically show the content on the project page
 +
** Keep the guide as concise as possible - it should contain a few words and a link to the website/wiki for details and more information
 +
** Use plain text, more complex structures can be provided in a Wiki
 +
* Describe any further project specific rules, which the contributors should know, for example:
 +
** preferences on code quality
 +
** code formatting
 +
** processes for code review
 +
* Projects may slightly different rules for contributing to different repositories. Make this clear to the contributors.
 +
 
 +
== Ideas what could be contributed to the project ==
 +
It may help people who would like to contribute to the project if you list some ideas for improvements which the team already knows, some areas where help is needed.
 +
 
 +
Keeping this sort of thing up-to-date can be challenging. Consider including a Bugzilla query (e.g. for "helpwanted" bugs) rather than (or in addition to) specific work area recommendations.
 +
 
 +
See for [[Mylyn/Contributor_Reference#Getting Started|example]] the Mylin contributor guide and how they provided a [https://bugs.eclipse.org/bugs/buglist.cgi?keywords=helpwanted&query_format=advanced&keywords_type=allwords&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&classification=Mylyn&list_id=5516643|"helpwanted"] query for the Mylin project.
  
 
= Tools =
 
= Tools =
This section contains brief information on concrete tools, frequently mentioned in the contribution guides
+
This section contains brief information on concrete tools, frequently mentioned in the contribution guides.
 
== Getting the Sources ==
 
== Getting the Sources ==
 
* For projects in Git usually [http://www.eclipse.org/egit/download/ EGit] is used. See the [[EGit|Contributor_Guide#From an installed EGit plugin]]
 
* For projects in Git usually [http://www.eclipse.org/egit/download/ EGit] is used. See the [[EGit|Contributor_Guide#From an installed EGit plugin]]
* For projects in SVN usually [http://www.eclipse.org/subversive/ Subversive] is used. Project Set files (psf) may also be provided.
+
* For projects in SVN usually [http://www.eclipse.org/subversive/ Subversive] is used.  
 +
 
 +
Project Set files (psf) should also be provided.
  
 
== Using an Explicit Target Platform Definition ==
 
== Using an Explicit Target Platform Definition ==
Line 26: Line 53:
 
* import the projects (usually at this time there are compiling errors because of missing dependencies)
 
* import the projects (usually at this time there are compiling errors because of missing dependencies)
 
* open the target definition file and set it as target platform for the workspace - all dependencies are resolved
 
* open the target definition file and set it as target platform for the workspace - all dependencies are resolved
* start develpoing
+
* start developing
 
   
 
   
 
In addition, projects using Tycho as a build technology can use exactly the same target definition during the build. This guarantees that the dependencies used in the IDE and the ones fetched during the build are the same.
 
In addition, projects using Tycho as a build technology can use exactly the same target definition during the build. This guarantees that the dependencies used in the IDE and the ones fetched during the build are the same.
  
 
Target definition files should contain the strict necessary dependencies for the project to compile and execute. It's recommended setting includeSources attribute to true in .target files to provide to developers access to sources of the dependencies, when available, in their development environment (PDE) without effort; for Tycho builds, this attribute is ignored and does not add sources to the build target-platform.
 
Target definition files should contain the strict necessary dependencies for the project to compile and execute. It's recommended setting includeSources attribute to true in .target files to provide to developers access to sources of the dependencies, when available, in their development environment (PDE) without effort; for Tycho builds, this attribute is ignored and does not add sources to the build target-platform.
Project could maintain several target defintions, for example to match several version of Eclipse.
+
Project could maintain several target defintions, for example to match several versions of Eclipse.
 +
 
 +
= Source Code Repositories =
 +
 
 +
All project source code repositories must contain a contribution guide. This may be an abbreviated version of the main project contribution guide hosted elsewhere.
 +
 
 +
For Git repositories, the evolving convention is to include a file named "CONTRIBUTING" (or "CONTRIBUTING.md") in the repository root.
 +
 
 +
Minimally, the repository contributing guide must include:
 +
 
 +
* Link to the project website and documentation;
 +
* Communication channel (how do potential contributors contact the project team?);
 +
* Mechanics of how to actually contribute (pull requests accepted, via Gerrit, etc.);
 +
* Link to sign a CLA
 +
 
 +
Additionally, the guide might include:
 +
 
 +
* Link to downloads (optional); and
 +
* Link to the main project contribution guide.
 +
 
 +
== Automagic Generation ==
 +
Consider using the default CONTRIBUTING guide generator.
 +
 
 +
<nowiki>http://www.eclipse.org/projects/tools/default_contributing_file.php?id=</nowiki>''project-id''
 +
 
 +
Where ''project-id'' is the id associated with your project (e.g. technology.sapphire or rt.equinox).
 +
 
 +
For example:
 +
 
 +
http://www.eclipse.org/projects/tools/default_contributing_file.php?id=technology.sapphire
 +
 
 +
<pre>Contributing to Sapphire
 +
========================
 +
 
 +
Thanks for your interest in this project.
 +
 
 +
Project description:
 +
--------------------
 +
 
 +
Sapphire is a user interface development framework that improves productivity. Instead
 +
of focusing on individual widgets, layouts and data binding, the developers focus on
 +
modeling the semantics of the data and declaring the general intent of how the data it
 +
to be presented.
 +
 
 +
- https://projects.eclipse.org/projects/technology.sapphire
 +
 
 +
Developer resources:
 +
--------------------
 +
 
 +
Information regarding source code management, builds, coding standards, and more.
 +
 
 +
- https://projects.eclipse.org/projects/technology.sapphire/developer
 +
 
 +
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" list.
 +
 
 +
- https://dev.eclipse.org/mailman/listinfo/sapphire-dev
 +
 
 +
Search for bugs:
 +
----------------
 +
 
 +
This project uses Bugzilla to track ongoing development and issues.
 +
 
 +
- https://bugs.eclipse.org/bugs/buglist.cgi?product=Sapphire
 +
 
 +
Create a new bug:
 +
-----------------
 +
 
 +
Be sure to search for existing bugs before you create another one. Remember
 +
that contributions are always welcome!
 +
 
 +
- https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Sapphire</pre>
 +
 
 +
This content is generated from the information that you provide in your project metadata in the PMI.
  
== Exported P2 Installations ==
+
See discussion in {{Bug|397644}}.
TODO
+
  
 
= Examples =  
 
= Examples =  

Revision as of 14:27, 15 September 2015

Contributor Guide - Motivation

Having concise and clear information how to get involved in a project is very important for building the community around a project. Therefore, to simplify adoption and encourage contributions it is recommended that projects maintain a "Contributor Guide" page.

What a Contributor Guide Should / Could Contain?

Below are some hints what a contributor guide should contain.

Setting up the development environment

Make it easy for people who got interested in your project to start playing with it

  • Provide a clear description how to get the sources in the IDE. See an example.
  • Describe how to setup any additional tools needed for the development. See an example.
  • Describe what the dependencites of the project are, or even better how to easily get all the necessary libraries the project depends on. Provide for example a target platform definition (see Tools below). See an example.
  • Describe any necessary steps to build the artifacts of the project (e.g. bundles, features, standalone products). See an example.

Contributing Code

Make it very clear what are the steps a contributor needs to follow, so that his contribution reaches the project and may be accepted

  • Include very specific instructions on how contributions are accepted. For example, if the project accept contributions via Gerrit, describe the mechanics of using Gerrit for the contribution
  • Indicate whether or not the project will accept GitHub pull requests. If yes, then describe the necessary steps to have the project honor those requests.
  • Describe the legal part of the proccess for accepting contributions, e.g. the three questions which should be answered, references to the CLA / CoO (both still drafts)
  • Provide a CONTRIBUTING file in the root of each repository
    • Due to the nature of Git, repositories get copied around a lot. Mirrors are hosted in various locations that may or may not have a connection back to the project website. There is an evolving standard of putting "CONTRIBUTING" file in the root of each repository
    • Keep the file in a "standard" location - the root of the repository. This could allow tools like the PMI to magically show the content on the project page
    • Keep the guide as concise as possible - it should contain a few words and a link to the website/wiki for details and more information
    • Use plain text, more complex structures can be provided in a Wiki
  • Describe any further project specific rules, which the contributors should know, for example:
    • preferences on code quality
    • code formatting
    • processes for code review
  • Projects may slightly different rules for contributing to different repositories. Make this clear to the contributors.

Ideas what could be contributed to the project

It may help people who would like to contribute to the project if you list some ideas for improvements which the team already knows, some areas where help is needed.

Keeping this sort of thing up-to-date can be challenging. Consider including a Bugzilla query (e.g. for "helpwanted" bugs) rather than (or in addition to) specific work area recommendations.

See for example the Mylin contributor guide and how they provided a "helpwanted" query for the Mylin project.

Tools

This section contains brief information on concrete tools, frequently mentioned in the contribution guides.

Getting the Sources

Project Set files (psf) should also be provided.

Using an Explicit Target Platform Definition

One technical possibility for projects to simplify the handling of dependencies is to provide one or more target definition files. Such files can be stored in the repository together with the sources and should be promoted on the "How to Contribute" page.

Using a target definition file, one can setup the workspace with a few steps:

  • clone (or checkout) source from the repository
  • import the projects (usually at this time there are compiling errors because of missing dependencies)
  • open the target definition file and set it as target platform for the workspace - all dependencies are resolved
  • start developing

In addition, projects using Tycho as a build technology can use exactly the same target definition during the build. This guarantees that the dependencies used in the IDE and the ones fetched during the build are the same.

Target definition files should contain the strict necessary dependencies for the project to compile and execute. It's recommended setting includeSources attribute to true in .target files to provide to developers access to sources of the dependencies, when available, in their development environment (PDE) without effort; for Tycho builds, this attribute is ignored and does not add sources to the build target-platform. Project could maintain several target defintions, for example to match several versions of Eclipse.

Source Code Repositories

All project source code repositories must contain a contribution guide. This may be an abbreviated version of the main project contribution guide hosted elsewhere.

For Git repositories, the evolving convention is to include a file named "CONTRIBUTING" (or "CONTRIBUTING.md") in the repository root.

Minimally, the repository contributing guide must include:

  • Link to the project website and documentation;
  • Communication channel (how do potential contributors contact the project team?);
  • Mechanics of how to actually contribute (pull requests accepted, via Gerrit, etc.);
  • Link to sign a CLA

Additionally, the guide might include:

  • Link to downloads (optional); and
  • Link to the main project contribution guide.

Automagic Generation

Consider using the default CONTRIBUTING guide generator.

http://www.eclipse.org/projects/tools/default_contributing_file.php?id=project-id

Where project-id is the id associated with your project (e.g. technology.sapphire or rt.equinox).

For example:

http://www.eclipse.org/projects/tools/default_contributing_file.php?id=technology.sapphire

Contributing to Sapphire
========================

Thanks for your interest in this project.

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

Sapphire is a user interface development framework that improves productivity. Instead 
of focusing on individual widgets, layouts and data binding, the developers focus on 
modeling the semantics of the data and declaring the general intent of how the data it 
to be presented.

- https://projects.eclipse.org/projects/technology.sapphire

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

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

- https://projects.eclipse.org/projects/technology.sapphire/developer

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" list.

- https://dev.eclipse.org/mailman/listinfo/sapphire-dev

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

This project uses Bugzilla to track ongoing development and issues.

- https://bugs.eclipse.org/bugs/buglist.cgi?product=Sapphire

Create a new bug:
-----------------

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

- https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Sapphire

This content is generated from the information that you provide in your project metadata in the PMI.

See discussion in bug 397644.

Examples

There are many projects at Eclipse which provide a "How to contribute" description. Just to name a few examples:

Back to the top