Difference between revisions of "Development Resources/IP Log"

From Eclipsepedia

Jump to: navigation, search
(Contributions)
(11 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
*Third-party libraries; and
 
*Third-party libraries; and
 
*Contributions from outside the project (i.e. non-committers)
 
*Contributions from outside the project (i.e. non-committers)
 +
 +
Note that a single IP Log can be generated for multiple, nested projects. A project might, for example, include one or more of its subprojects in a release. In that event, a single consolidated log for all contained projects can be provided (creation of consolidated logs is supported by the tools).
  
 
The [http://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf Eclipse IP Policy] document describes (in fairly broad terms) the requirement for an IP Log. The [http://www.eclipse.org/projects/dev_process/project-log.php Project IP Log] page provides the definitive guide for what should be in your IP Log.  
 
The [http://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf Eclipse IP Policy] document describes (in fairly broad terms) the requirement for an IP Log. The [http://www.eclipse.org/projects/dev_process/project-log.php Project IP Log] page provides the definitive guide for what should be in your IP Log.  
  
The existing [[Development Resources/Automatic IP Log|Automatic IP Log Tool]] and the new EMF-based one under development by the [http://www.eclipse.org/woolsey Woolsey Project] can help you build your IP Log. The key word here is "help"; ultimately, these are just tools that gather the information that is available. These tools are only as good as the input provided.
+
The existing [[Development Resources/Automatic IP Log|Automatic IP Log Tool]] can help you build your IP Log. The key word here is "help"; ultimately, this is just a tool that gathers the information that is available. The generated output is only as good as the input provided. It is limited in its ability to--for example--attribute a contribution to more than one contributor. You can use the automatic tool to generate a [[Development Resources/Automatic IP Log#Manually Generate the IP Log|baseline IP Log that you can modify]] if necessary.
  
The [http://www.eclipse.org/projects/tools/ip_contribution_review.php IP Contributions Review] project tool can help you identify bugs that may contain IP contributions that should be noted in your log.
+
The [http://www.eclipse.org/projects/tools/ip_contribution_review.php IP Contributions Review] project tool can help you identify bugs that may contain IP contributions that should be noted in your log (this is generally useful only for contributions accepted by a project before adopting Git). Please see [[Development Resources/Handling Git Contributions|Handling Git Contributions]].
  
 
==Licenses==
 
==Licenses==
Line 17: Line 19:
  
 
The automated tools obtain this information from the Eclipse Foundation Database. If the information in the automated tools is not correct, please contact the [mailto:emo@eclipse.org EMO] to resolve the issue.
 
The automated tools obtain this information from the Eclipse Foundation Database. If the information in the automated tools is not correct, please contact the [mailto:emo@eclipse.org EMO] to resolve the issue.
 +
 +
==Past and Present Committers==
 +
 +
This section must include the identity of every committer (past and present) on the project. It is generally enough to record the name and affiliation of each committer; email addresses and personal information should generally ''not'' be recorded.
 +
 +
The automated tools obtain this information from a combination of sources. First, the Dash database is mined for the identity of anybody who has committed code into any of the project's listed repositories. This information is only as good as the data recorded about the project in the portal (Dash runs weekly, so you may have to wait for this information to be updated). It is worth noting that--as of August 2010--Dash does not gather commit activity for any Git repositories. Second, the automated tools gather information from the Eclipse Foundation Database, where records of all committers are recorded. The combination of information is used to determine the name and level of activity of each committer.
  
 
==Third-Party Libraries==
 
==Third-Party Libraries==
  
Any third-party libraries that the project uses must be recorded in the log. Furthermore, these libraries must have all been taken through the Eclipse IP Process. As part of that process, a [[Contribution Questionnaire]] (CQ) must have been created for each library.  
+
Any third-party libraries that the project uses must be recorded in the log. Furthermore, these libraries must have all been taken through the Eclipse IP Process. As part of that process, a [[Development Resources/New Commmitter Handbook#Contribution Questionnaire_.28CQ.29 | contribution questionnaire]] (CQ) must have been created for each library.  
  
 
The automated tools will populate this section of the IP Log with information taken from the CQs. If you are using the automated tools to generate this information, it is your responsibility to ensure that it is accurate. Report any problems to the [mailto:emo-ip-team@eclipse.org EMO IP Team].
 
The automated tools will populate this section of the IP Log with information taken from the CQs. If you are using the automated tools to generate this information, it is your responsibility to ensure that it is accurate. Report any problems to the [mailto:emo-ip-team@eclipse.org EMO IP Team].
  
 
==Contributions==
 
==Contributions==
 
You need to record all the contributions that your project receives. All contributions should be accepted through Bugzilla. Ideally, contributions should be attached to the Bugzilla record that defines the bug that the contribution addresses. By attaching the patch to a Bugzilla record, the contributor implicitly agrees to the [http://www.eclipse.org/legal/termsofuse.php Eclipse terms of use] (which, effectively, grants your project certain rights to use the contribution). Despite the implicit agreement, it's a good idea to get some kind of explicit endorsement from the contributor that it's okay to include the code in your project and distribute it under the license your project distributes code under (generally the EPL).
 
  
 
Some thoughts:
 
Some thoughts:
  
* Only actual code contributions need to be included in the IP Log;
+
* Only actual contributions that end up in the code base (which may include code, configuration, images, etc.) need to be included in the IP Log;
 +
* Ideas, pseudo-code, etc. do not belong in the IP Log (unless they are, for example, directly included in the code, perhaps as comments, or input into an automated process).
 
* Only contributions from non-committers need to be included in the IP Log;  
 
* Only contributions from non-committers need to be included in the IP Log;  
 
* Contributions that come from a developer before they become a committer do need to be included in the IP Log; and
 
* Contributions that come from a developer before they become a committer do need to be included in the IP Log; and
Line 37: Line 44:
 
While your committers can attach patches to bugs, they generally don't need to (so long as they are observing the [http://eclipse.org/legal/EclipseLegalProcessPoster.pdf IP Due Diligence process]).
 
While your committers can attach patches to bugs, they generally don't need to (so long as they are observing the [http://eclipse.org/legal/EclipseLegalProcessPoster.pdf IP Due Diligence process]).
  
The IP Log tools provide a lot of help with contributions. But you need to do some work to leverage this help. If you set the iplog flag on an attachment that contains a contribution (e..g a patch), that contribution will appear in an automatically-generated log (note that, iplog+ marked contributions from existing committers will be skipped). This is probably the most natural way to use the flag. To set this flag, open the "Details" for the attachment, set the value to “+”, and commit. That’s it. Do this for any attachment that contains something that you’ve committed into an Eclipse source code repository. This includes things like code patches, image files, XML schemas, and pretty much anything else. Only mark those attachments that actually make it into the project's code repository; just leave any other attachments alone. Unfortunately, there is no current support for setting the iplog flag from [http://www.eclipse.org/mylyn Mylyn], so you'll have to use a browser.
+
The IP Log tools provide a lot of help with contributions. But you need to do some work to leverage this help.  
 +
 
 +
===Contributions and Git===
 +
 
 +
The automated IP Log will automatically pick up contributions made into a project's Git repository if the Git commit record's "author" field is set (the Git repository must be listed in the project's <code>sourcerepositories</code> metadata). Specifically, the "author" fields should be set to the name and email address of the contributor. The "committer" fields should be set to the information for the committer (it will otherwise be rejected).
 +
 
 +
For more information, please see [[Development Resources/Handling Git Contributions|Handling Git Contributions]].
 +
 
 +
===Contributions and Bugzilla===
 +
In the good old days of CVS, all contributions needed to flow through Bugzilla. This is still true for projects using SVN. Even for projects using Git, some contributions will flow through Bugzilla.
 +
 
 +
Contributions should be attached to the Bugzilla record that defines the bug that the contribution addresses. Be sure the follow the process as documented in the [http://eclipse.org/legal/EclipseLegalProcessPoster.pdf IP Due Diligence process]. In particular, the contributor (author) must provide a statement regarding the provenance, rights, and license of the code in a comment on the Bugzilla record, e.g.
 +
 
 +
I assert that I:
 +
1. authored 100% the content they are contributing
 +
2. have the rights to donate the content to Eclipse
 +
3. contribute the content under the EPL
 +
 
 +
Mark patches and other attachments as contributions by turning on the iplog+ flag. There is more information on this below.
 +
 
 +
Note that the [http://www.eclipse.org/projects/tools/ip_contribution_review.php IP Contributions Review tool] can ''help'' you to identify bugs and attachments that are potential IP contributions.
 +
 
 +
===Contributions and CVS/SVN===
 +
 
 +
CVS and SVN have no means of keeping track of author information separate from the committer, so we need to give the automated IP Log a little more help.
 +
 
 +
All contributions that end up in a CVS or SVN repository must be accepted through Bugzilla.
 +
 
 +
If you set the iplog flag on an attachment that contains a contribution (e.g. a patch), that contribution will appear in an automatically-generated log (note that, iplog+ marked contributions from existing committers will be skipped). This is probably the most natural way to use the flag. To set this flag, open the "Details" for the attachment, set the value to “+”, and commit. That’s it. Do this for any attachment that contains something that you’ve committed into an Eclipse source code repository. This includes things like code patches, image files, XML schemas, and pretty much anything else. Only mark those attachments that actually make it into the project's code repository; just leave any other attachments alone.
  
 
You can also set the iplog flag on an entire bug. You would do this if the bug’s summary or one of the comments contains code, or some other valuable asset that you commit into the source code repository. Unfortunately, flagging the bug indicates to the automated tools that every comment on the bug is a potential contribution (sadly, there is no way to set a flag on an individual comment). When you set the flag on the entire bug, you have to manually go through the generated log and remove any comments that shouldn’t be there. Yes, this can be painful. It’s made more painful by the fact that any new comments added to the bug after you’ve done your clean up will appear the next time the log is generated. This is particularly troublesome in the current Automatic IP Log Tool, and only slightly less so with the new one.
 
You can also set the iplog flag on an entire bug. You would do this if the bug’s summary or one of the comments contains code, or some other valuable asset that you commit into the source code repository. Unfortunately, flagging the bug indicates to the automated tools that every comment on the bug is a potential contribution (sadly, there is no way to set a flag on an individual comment). When you set the flag on the entire bug, you have to manually go through the generated log and remove any comments that shouldn’t be there. Yes, this can be painful. It’s made more painful by the fact that any new comments added to the bug after you’ve done your clean up will appear the next time the log is generated. This is particularly troublesome in the current Automatic IP Log Tool, and only slightly less so with the new one.
Line 44: Line 79:
  
 
Only those attachments and bugs that contain contributions from developers who are not committers on the project at the time need be flagged. This is time-sensitive. If the contributor eventually does become a committer, those patches they’ve contributed while they were not a committer still need to be accounted for in the log and must therefore be flagged. The tools are smart enough to check the dates. Make sure that each committer’s Bugzilla email address matches the one in the Eclipse Foundation database, or you'll wind up with some extra stuff in your IP Log.
 
Only those attachments and bugs that contain contributions from developers who are not committers on the project at the time need be flagged. This is time-sensitive. If the contributor eventually does become a committer, those patches they’ve contributed while they were not a committer still need to be accounted for in the log and must therefore be flagged. The tools are smart enough to check the dates. Make sure that each committer’s Bugzilla email address matches the one in the Eclipse Foundation database, or you'll wind up with some extra stuff in your IP Log.
 +
 +
The [http://eclipse.org/projects/tools/ip_contribution_review.php IP Contribution Review Tool] can help you identify bugs/attachments that need to be marked iplog+.
  
 
''This page is moderated by the EMO''
 
''This page is moderated by the EMO''

Revision as of 15:22, 31 May 2013

The IP Log is a big part of the official release process. You are required to submit your project's IP Log prior to scheduling a release, or restructuring review. We encourage you to keep your IP log current rather than rushing at the end. The IP Log includes important information about your project that lets adopters know where all the code comes from, who owns the copyrights, and so forth. Specifically, the log tracks:

  • Licenses;
  • Past and present committers;
  • Third-party libraries; and
  • Contributions from outside the project (i.e. non-committers)

Note that a single IP Log can be generated for multiple, nested projects. A project might, for example, include one or more of its subprojects in a release. In that event, a single consolidated log for all contained projects can be provided (creation of consolidated logs is supported by the tools).

The Eclipse IP Policy document describes (in fairly broad terms) the requirement for an IP Log. The Project IP Log page provides the definitive guide for what should be in your IP Log.

The existing Automatic IP Log Tool can help you build your IP Log. The key word here is "help"; ultimately, this is just a tool that gathers the information that is available. The generated output is only as good as the input provided. It is limited in its ability to--for example--attribute a contribution to more than one contributor. You can use the automatic tool to generate a baseline IP Log that you can modify if necessary.

The IP Contributions Review project tool can help you identify bugs that may contain IP contributions that should be noted in your log (this is generally useful only for contributions accepted by a project before adopting Git). Please see Handling Git Contributions.

Contents

Licenses

The "license" section lists the licenses that the project itself is released under. For most projects, this should be the Eclipse Public License (EPL) only. Though, projects like JGit release under the Eclipse Distribution License (EDL); and EclipseLink releases under both the EPL and EDL. Normally, all other licenses are indicated in the "third-party libraries" sections.

The automated tools obtain this information from the Eclipse Foundation Database. If the information in the automated tools is not correct, please contact the EMO to resolve the issue.

Past and Present Committers

This section must include the identity of every committer (past and present) on the project. It is generally enough to record the name and affiliation of each committer; email addresses and personal information should generally not be recorded.

The automated tools obtain this information from a combination of sources. First, the Dash database is mined for the identity of anybody who has committed code into any of the project's listed repositories. This information is only as good as the data recorded about the project in the portal (Dash runs weekly, so you may have to wait for this information to be updated). It is worth noting that--as of August 2010--Dash does not gather commit activity for any Git repositories. Second, the automated tools gather information from the Eclipse Foundation Database, where records of all committers are recorded. The combination of information is used to determine the name and level of activity of each committer.

Third-Party Libraries

Any third-party libraries that the project uses must be recorded in the log. Furthermore, these libraries must have all been taken through the Eclipse IP Process. As part of that process, a contribution questionnaire (CQ) must have been created for each library.

The automated tools will populate this section of the IP Log with information taken from the CQs. If you are using the automated tools to generate this information, it is your responsibility to ensure that it is accurate. Report any problems to the EMO IP Team.

Contributions

Some thoughts:

  • Only actual contributions that end up in the code base (which may include code, configuration, images, etc.) need to be included in the IP Log;
  • Ideas, pseudo-code, etc. do not belong in the IP Log (unless they are, for example, directly included in the code, perhaps as comments, or input into an automated process).
  • Only contributions from non-committers need to be included in the IP Log;
  • Contributions that come from a developer before they become a committer do need to be included in the IP Log; and
  • All contributions in the current code base (as of the time of the creation of the log) need to be included in the log (regardless of whether or not they have been noted in previous logs).

While your committers can attach patches to bugs, they generally don't need to (so long as they are observing the IP Due Diligence process).

The IP Log tools provide a lot of help with contributions. But you need to do some work to leverage this help.

Contributions and Git

The automated IP Log will automatically pick up contributions made into a project's Git repository if the Git commit record's "author" field is set (the Git repository must be listed in the project's sourcerepositories metadata). Specifically, the "author" fields should be set to the name and email address of the contributor. The "committer" fields should be set to the information for the committer (it will otherwise be rejected).

For more information, please see Handling Git Contributions.

Contributions and Bugzilla

In the good old days of CVS, all contributions needed to flow through Bugzilla. This is still true for projects using SVN. Even for projects using Git, some contributions will flow through Bugzilla.

Contributions should be attached to the Bugzilla record that defines the bug that the contribution addresses. Be sure the follow the process as documented in the IP Due Diligence process. In particular, the contributor (author) must provide a statement regarding the provenance, rights, and license of the code in a comment on the Bugzilla record, e.g.

I assert that I:
1. authored 100% the content they are contributing
2. have the rights to donate the content to Eclipse
3. contribute the content under the EPL

Mark patches and other attachments as contributions by turning on the iplog+ flag. There is more information on this below.

Note that the IP Contributions Review tool can help you to identify bugs and attachments that are potential IP contributions.

Contributions and CVS/SVN

CVS and SVN have no means of keeping track of author information separate from the committer, so we need to give the automated IP Log a little more help.

All contributions that end up in a CVS or SVN repository must be accepted through Bugzilla.

If you set the iplog flag on an attachment that contains a contribution (e.g. a patch), that contribution will appear in an automatically-generated log (note that, iplog+ marked contributions from existing committers will be skipped). This is probably the most natural way to use the flag. To set this flag, open the "Details" for the attachment, set the value to “+”, and commit. That’s it. Do this for any attachment that contains something that you’ve committed into an Eclipse source code repository. This includes things like code patches, image files, XML schemas, and pretty much anything else. Only mark those attachments that actually make it into the project's code repository; just leave any other attachments alone.

You can also set the iplog flag on an entire bug. You would do this if the bug’s summary or one of the comments contains code, or some other valuable asset that you commit into the source code repository. Unfortunately, flagging the bug indicates to the automated tools that every comment on the bug is a potential contribution (sadly, there is no way to set a flag on an individual comment). When you set the flag on the entire bug, you have to manually go through the generated log and remove any comments that shouldn’t be there. Yes, this can be painful. It’s made more painful by the fact that any new comments added to the bug after you’ve done your clean up will appear the next time the log is generated. This is particularly troublesome in the current Automatic IP Log Tool, and only slightly less so with the new one.

The bottom line is that it is always easier if your contributions come in the form of an attachment.

Only those attachments and bugs that contain contributions from developers who are not committers on the project at the time need be flagged. This is time-sensitive. If the contributor eventually does become a committer, those patches they’ve contributed while they were not a committer still need to be accounted for in the log and must therefore be flagged. The tools are smart enough to check the dates. Make sure that each committer’s Bugzilla email address matches the one in the Eclipse Foundation database, or you'll wind up with some extra stuff in your IP Log.

The IP Contribution Review Tool can help you identify bugs/attachments that need to be marked iplog+.

This page is moderated by the EMO