You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@uima.apache.org by Richard Eckart de Castilho <ec...@ukp.informatik.tu-darmstadt.de> on 2013/02/22 17:45:03 UTC
javadoc, tests and test-source artifacts in releases?
Hi there,
I'm looking on reorganizing the uimaFIT build/release process to ramp up to a first RC.
Doing that, I notice that UIMA artifacts on Maven Central do not have javadoc.jar test.jar and test-sources.jar. In past uimaFIT builds, we included all of these. Is there any particular reason why these artifacts are not generated, attached and deployed?
Cheers,
-- Richard
--
-------------------------------------------------------------------
Richard Eckart de Castilho
Technical Lead
Ubiquitous Knowledge Processing Lab (UKP-TUD)
FB 20 Computer Science Department
Technische Universität Darmstadt
Hochschulstr. 10, D-64289 Darmstadt, Germany
phone [+49] (0)6151 16-7477, fax -5455, room S2/02/B117
eckart@ukp.informatik.tu-darmstadt.de
www.ukp.tu-darmstadt.de
Web Research at TU Darmstadt (WeRC) www.werc.tu-darmstadt.de
-------------------------------------------------------------------
Re: javadoc, tests and test-source artifacts in releases?
Posted by Marshall Schor <ms...@schor.com>.
On 2/25/2013 2:06 AM, Richard Eckart de Castilho wrote:
> Hi,
>
>>> The execution "javadocs-distr" in the "uimaj" POM (the one in trunk) runs the
>>> "javadoc" goal, not the "aggregate" goal. That looks like only per-module
>>> JavaDoc is generated. It appears to be the only place where the JavaDoc
>>> plugin is configured. Where is the aggregate JavaDoc generated and how is
>>> it later published?
>> This generates the aggregate javadoc. I recall, vaguely, that the aggregate
>> goal assumed we wanted javadocs for everything, instead of just for the
>> user-accessible APIs.
>>
>> To get the aggregate set generated, this goal has a configuration which includes
>> specifying multiple "sourcepath" elements, one for each module that has
>> user-referenced APIs. And then it also includes some
>> otherwise-by-default-excluded packages that have the word "impl" in them (which
>> is one of the naming convention we used for internal, implementation-detail,
>> subject to change, etc., kind of packages). See the "excludePackageNames"
>> element in the configuration for the javadoc in the POM.
> Hm, I'll check this again and possibly stick with "aggregate" for uimaFIT then.
>
>>>> The third is that tools like Eclipse can get the source from Maven (the
>>>> source.jar) when needed for debugging, automatically. It's unclear (to me at
>>>> least) the use case(s) that would make use of the JavaDocs-by-module on Maven
>>>> central.
>>> For Eclipse, the JavaDoc artifacts are indeed quite redundant, at least if the
>>> sources are available. In principle, it could be imagined, though, that the
>>> JavaDoc is post-processed and augmented, so that it contains more information
>>> than the "plain" JavaDoc from the source.
>>>
>>>> Likewise, I'm not sure what the use-case(s) are for putting the test-sources on
>>>> Maven Central. Tests are typically done during builds, and those are done
>>>> typically by developers, who checked out the sources from SVN.
>>> It's not a good practice, but it's possible to reference a test artifact from
>>> module A so it can be used by the tests in module B.
>> I'm not sure how this would work in practice. Normally, Maven dependencies
>> refer to JAR artifacts (or compiled folders) that can be put into the classpath
>> of something, like a test-runner. I don't see how putting a reference to a
>> Maven-located artifact which was a "source" artifact would work?
> Badly written on my side. I meant putting the test-jars there for reference from
> other tests. When the test-jars are there, having the test-sources as well is -
> of course - convenient. Addressing a test artifact is done by adding a "classifier"
> to the dependency. I'm not promoting this kind of dependencies between tests.
OK - this could work, and if there was a need for this, it would be OK with
me. However, I think the normal maven builds don't build test jars? I think
this is one of those kinds of things that, although "do-able", kind of goes
against normal Maven conventions. The way we have "shared" things needed for
testing, in the past, has been to put them into a separate project, where we use
the normal Maven conventions of having these in the src/main/java spot, not in
the test/ spot, so normal Maven conventions results in building these Jars, etc.
For example, see the project uimaj-test-util in uimaj. This is included as a
"dependency" where needed by the tests, just as you have suggested.
-Marshall
>
> Cheers,
>
> -- Richard
>
Re: javadoc, tests and test-source artifacts in releases?
Posted by Richard Eckart de Castilho <ec...@ukp.informatik.tu-darmstadt.de>.
Hi,
>> The execution "javadocs-distr" in the "uimaj" POM (the one in trunk) runs the
>> "javadoc" goal, not the "aggregate" goal. That looks like only per-module
>> JavaDoc is generated. It appears to be the only place where the JavaDoc
>> plugin is configured. Where is the aggregate JavaDoc generated and how is
>> it later published?
>
> This generates the aggregate javadoc. I recall, vaguely, that the aggregate
> goal assumed we wanted javadocs for everything, instead of just for the
> user-accessible APIs.
>
> To get the aggregate set generated, this goal has a configuration which includes
> specifying multiple "sourcepath" elements, one for each module that has
> user-referenced APIs. And then it also includes some
> otherwise-by-default-excluded packages that have the word "impl" in them (which
> is one of the naming convention we used for internal, implementation-detail,
> subject to change, etc., kind of packages). See the "excludePackageNames"
> element in the configuration for the javadoc in the POM.
Hm, I'll check this again and possibly stick with "aggregate" for uimaFIT then.
>>> The third is that tools like Eclipse can get the source from Maven (the
>>> source.jar) when needed for debugging, automatically. It's unclear (to me at
>>> least) the use case(s) that would make use of the JavaDocs-by-module on Maven
>>> central.
>> For Eclipse, the JavaDoc artifacts are indeed quite redundant, at least if the
>> sources are available. In principle, it could be imagined, though, that the
>> JavaDoc is post-processed and augmented, so that it contains more information
>> than the "plain" JavaDoc from the source.
>>
>>> Likewise, I'm not sure what the use-case(s) are for putting the test-sources on
>>> Maven Central. Tests are typically done during builds, and those are done
>>> typically by developers, who checked out the sources from SVN.
>> It's not a good practice, but it's possible to reference a test artifact from
>> module A so it can be used by the tests in module B.
> I'm not sure how this would work in practice. Normally, Maven dependencies
> refer to JAR artifacts (or compiled folders) that can be put into the classpath
> of something, like a test-runner. I don't see how putting a reference to a
> Maven-located artifact which was a "source" artifact would work?
Badly written on my side. I meant putting the test-jars there for reference from
other tests. When the test-jars are there, having the test-sources as well is -
of course - convenient. Addressing a test artifact is done by adding a "classifier"
to the dependency. I'm not promoting this kind of dependencies between tests.
Cheers,
-- Richard
--
-------------------------------------------------------------------
Richard Eckart de Castilho
Technical Lead
Ubiquitous Knowledge Processing Lab (UKP-TUD)
FB 20 Computer Science Department
Technische Universität Darmstadt
Hochschulstr. 10, D-64289 Darmstadt, Germany
phone [+49] (0)6151 16-7477, fax -5455, room S2/02/B117
eckart@ukp.informatik.tu-darmstadt.de
www.ukp.tu-darmstadt.de
Web Research at TU Darmstadt (WeRC) www.werc.tu-darmstadt.de
-------------------------------------------------------------------
Re: javadoc, tests and test-source artifacts in releases?
Posted by Marshall Schor <ms...@schor.com>.
On 2/23/2013 1:34 PM, Richard Eckart de Castilho wrote:
> Hi,
>
> thanks for the feedback. So, no javadoc, test-sources and test-javadoc artifacts, ok.
> I still do not get how the javadoc is built and published - see the comments below.
>
>> On 2/22/2013 11:45 AM, Richard Eckart de Castilho wrote:
>>> Hi there,
>>>
>>> I'm looking on reorganizing the uimaFIT build/release process to ramp up to a first RC.
>>>
>>> Doing that, I notice that UIMA artifacts on Maven Central do not have javadoc.jar test.jar and test-sources.jar. In past uimaFIT builds, we included all of these. Is there any particular reason why these artifacts are not generated, attached and deployed?
>> Re Javadocs: There are 3 reasons, I think (maybe others can chime in...)
>>
>> The first is a granularity issue. We normally release Javadocs for the entire
>> release, not just for one "module"; many of our released artifacts have multiple
>> sub-projects, and we want to release one comprehensive Javadoc for all of the
>> content.
>>
>> The second is to have a filtered Javadoc for users which only contains
>> user-accessible methods we pay attention to keeping stable, and excluding
>> internal-use, subject-to-change implementation methods. Often, but not always,
>> this split can be done using Java's public/protected/package-private/private
>> designation. To support this, we have a release-time step which builds the
>> javadocs for the whole release, excluding "public" things which are not part of
>> the user-api set.
> The execution "javadocs-distr" in the "uimaj" POM (the one in trunk) runs the
> "javadoc" goal, not the "aggregate" goal. That looks like only per-module
> JavaDoc is generated. It appears to be the only place where the JavaDoc
> plugin is configured. Where is the aggregate JavaDoc generated and how is
> it later published?
This generates the aggregate javadoc. I recall, vaguely, that the aggregate
goal assumed we wanted javadocs for everything, instead of just for the
user-accessible APIs.
To get the aggregate set generated, this goal has a configuration which includes
specifying multiple "sourcepath" elements, one for each module that has
user-referenced APIs. And then it also includes some
otherwise-by-default-excluded packages that have the word "impl" in them (which
is one of the naming convention we used for internal, implementation-detail,
subject to change, etc., kind of packages). See the "excludePackageNames"
element in the configuration for the javadoc in the POM.
>
>> The third is that tools like Eclipse can get the source from Maven (the
>> source.jar) when needed for debugging, automatically. It's unclear (to me at
>> least) the use case(s) that would make use of the JavaDocs-by-module on Maven
>> central.
> For Eclipse, the JavaDoc artifacts are indeed quite redundant, at least if the
> sources are available. In principle, it could be imagined, though, that the
> JavaDoc is post-processed and augmented, so that it contains more information
> than the "plain" JavaDoc from the source.
>
>> Likewise, I'm not sure what the use-case(s) are for putting the test-sources on
>> Maven Central. Tests are typically done during builds, and those are done
>> typically by developers, who checked out the sources from SVN.
> It's not a good practice, but it's possible to reference a test artifact from
> module A so it can be used by the tests in module B.
I'm not sure how this would work in practice. Normally, Maven dependencies
refer to JAR artifacts (or compiled folders) that can be put into the classpath
of something, like a test-runner. I don't see how putting a reference to a
Maven-located artifact which was a "source" artifact would work?
-Marshall
>
> Cheers,
>
> -- Richard
>
Re: javadoc, tests and test-source artifacts in releases?
Posted by Richard Eckart de Castilho <ec...@ukp.informatik.tu-darmstadt.de>.
Hi,
thanks for the feedback. So, no javadoc, test-sources and test-javadoc artifacts, ok.
I still do not get how the javadoc is built and published - see the comments below.
> On 2/22/2013 11:45 AM, Richard Eckart de Castilho wrote:
>> Hi there,
>>
>> I'm looking on reorganizing the uimaFIT build/release process to ramp up to a first RC.
>>
>> Doing that, I notice that UIMA artifacts on Maven Central do not have javadoc.jar test.jar and test-sources.jar. In past uimaFIT builds, we included all of these. Is there any particular reason why these artifacts are not generated, attached and deployed?
>
> Re Javadocs: There are 3 reasons, I think (maybe others can chime in...)
>
> The first is a granularity issue. We normally release Javadocs for the entire
> release, not just for one "module"; many of our released artifacts have multiple
> sub-projects, and we want to release one comprehensive Javadoc for all of the
> content.
>
> The second is to have a filtered Javadoc for users which only contains
> user-accessible methods we pay attention to keeping stable, and excluding
> internal-use, subject-to-change implementation methods. Often, but not always,
> this split can be done using Java's public/protected/package-private/private
> designation. To support this, we have a release-time step which builds the
> javadocs for the whole release, excluding "public" things which are not part of
> the user-api set.
The execution "javadocs-distr" in the "uimaj" POM (the one in trunk) runs the
"javadoc" goal, not the "aggregate" goal. That looks like only per-module
JavaDoc is generated. It appears to be the only place where the JavaDoc
plugin is configured. Where is the aggregate JavaDoc generated and how is
it later published?
> The third is that tools like Eclipse can get the source from Maven (the
> source.jar) when needed for debugging, automatically. It's unclear (to me at
> least) the use case(s) that would make use of the JavaDocs-by-module on Maven
> central.
For Eclipse, the JavaDoc artifacts are indeed quite redundant, at least if the
sources are available. In principle, it could be imagined, though, that the
JavaDoc is post-processed and augmented, so that it contains more information
than the "plain" JavaDoc from the source.
> Likewise, I'm not sure what the use-case(s) are for putting the test-sources on
> Maven Central. Tests are typically done during builds, and those are done
> typically by developers, who checked out the sources from SVN.
It's not a good practice, but it's possible to reference a test artifact from
module A so it can be used by the tests in module B.
Cheers,
-- Richard
--
-------------------------------------------------------------------
Richard Eckart de Castilho
Technical Lead
Ubiquitous Knowledge Processing Lab (UKP-TUD)
FB 20 Computer Science Department
Technische Universität Darmstadt
Hochschulstr. 10, D-64289 Darmstadt, Germany
phone [+49] (0)6151 16-7477, fax -5455, room S2/02/B117
eckart@ukp.informatik.tu-darmstadt.de
www.ukp.tu-darmstadt.de
Web Research at TU Darmstadt (WeRC) www.werc.tu-darmstadt.de
-------------------------------------------------------------------
Re: javadoc, tests and test-source artifacts in releases?
Posted by Marshall Schor <ms...@schor.com>.
On 2/22/2013 11:45 AM, Richard Eckart de Castilho wrote:
> Hi there,
>
> I'm looking on reorganizing the uimaFIT build/release process to ramp up to a first RC.
>
> Doing that, I notice that UIMA artifacts on Maven Central do not have javadoc.jar test.jar and test-sources.jar. In past uimaFIT builds, we included all of these. Is there any particular reason why these artifacts are not generated, attached and deployed?
Re Javadocs: There are 3 reasons, I think (maybe others can chime in...)
The first is a granularity issue. We normally release Javadocs for the entire
release, not just for one "module"; many of our released artifacts have multiple
sub-projects, and we want to release one comprehensive Javadoc for all of the
content.
The second is to have a filtered Javadoc for users which only contains
user-accessible methods we pay attention to keeping stable, and excluding
internal-use, subject-to-change implementation methods. Often, but not always,
this split can be done using Java's public/protected/package-private/private
designation. To support this, we have a release-time step which builds the
javadocs for the whole release, excluding "public" things which are not part of
the user-api set.
The third is that tools like Eclipse can get the source from Maven (the
source.jar) when needed for debugging, automatically. It's unclear (to me at
least) the use case(s) that would make use of the JavaDocs-by-module on Maven
central.
Likewise, I'm not sure what the use-case(s) are for putting the test-sources on
Maven Central. Tests are typically done during builds, and those are done
typically by developers, who checked out the sources from SVN.
If there's no use, the builds go faster if these artifacts are not generated,
attached, and deployed :-).
-Marshall
>
> Cheers,
>
> -- Richard
>