You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles <gi...@harfang.homelinux.org> on 2018/02/10 13:58:54 UTC
[All] Convention for "courtesy" codes?
Hello.
Is there a convention for distinguishing codes with
compatibility requirements from codes provided as
development tools (unit tests, benchmarking, usage
examples, integration tests, ...)?
For unit tests, there is a convention: "main" vs "test".
The latter has no backward-compatibility requirement.
But how would a project convey that some of its
distributed files will not abide by any compatiblity
requirement even if the source is in "main".
A concrete example in "Commons RNG": the (maven) module
"commons-rng-jmh" contains source codes whose purpose is
to benchmark the codes provided in other modules (e.g.
"common-rng-sampling"). Clearly, it was never intended
that "JMH"-based benchmarking is considered part of the
"Commons RNG" library. The same is true of the examples
(in "commons-rng-examples") or the additional integration
tests (suggested by Simon) that would go in yet another
maven module.
So, is a simple warning in the release notes sufficient
to signal "courtesy" codes?
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [All] Convention for "courtesy" codes?
Posted by Gilles <gi...@harfang.homelinux.org>.
On Sat, 10 Feb 2018 20:50:26 +0100, Stefan Bodewig wrote:
> On 2018-02-10, Gilles wrote:
>
>> On Sat, 10 Feb 2018 08:08:12 -0700, Gary Gregory wrote:
>>> If a Java package and artifact ID contain "internal" or "private"
>>> in
>>> the
>>> name, that would be pretty clear.
>
>> Do you suggest that, say, the benchmarking codes in
>> "commons-rng-jmh" should be located in a top package
>> named "o.a.c.rng.jmh.internal"?
>
> Gary's response likely stems from me misunderstanding what you asked
> about. I overlooked you said "modules" and assumed you were talking
> about parts of an artifact which otherwise should evolve in a
> backwards
> compatible way.
>
> If a whole artifact is not considered something that is there for
> public
> consumption as an API then I'd just say so (inside the POM, in
> javadocs,
> on the website ...) and not care for backwards compatibility at all.
>
> IMHO we don't need any rules for something like this, proper
> documentaton should be enough.
I'll then also assume that the layout of the maven project
can be chosen freely for those packages/modules.
For clarity's sake, in the case of "Commons RNG", I intend
to move all "non-library" codes to sub-modules of module
"commons-rng-examples".
Any objections?
Gilles
>
> Stefan
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [All] Convention for "courtesy" codes?
Posted by Gilles <gi...@harfang.homelinux.org>.
On Sat, 10 Feb 2018 20:50:26 +0100, Stefan Bodewig wrote:
> On 2018-02-10, Gilles wrote:
>
>> On Sat, 10 Feb 2018 08:08:12 -0700, Gary Gregory wrote:
>>> If a Java package and artifact ID contain "internal" or "private"
>>> in
>>> the
>>> name, that would be pretty clear.
>
>> Do you suggest that, say, the benchmarking codes in
>> "commons-rng-jmh" should be located in a top package
>> named "o.a.c.rng.jmh.internal"?
>
> Gary's response likely stems from me misunderstanding what you asked
> about. I overlooked you said "modules" and assumed you were talking
> about parts of an artifact which otherwise should evolve in a
> backwards
> compatible way.
>
> If a whole artifact is not considered something that is there for
> public
> consumption as an API then I'd just say so (inside the POM, in
> javadocs,
> on the website ...) and not care for backwards compatibility at all.
>
> IMHO we don't need any rules for something like this, proper
> documentaton should be enough.
Good.
Thanks,
Gilles
> Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [All] Convention for "courtesy" codes?
Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-02-10, Gilles wrote:
> On Sat, 10 Feb 2018 08:08:12 -0700, Gary Gregory wrote:
>> If a Java package and artifact ID contain "internal" or "private" in
>> the
>> name, that would be pretty clear.
> Do you suggest that, say, the benchmarking codes in
> "commons-rng-jmh" should be located in a top package
> named "o.a.c.rng.jmh.internal"?
Gary's response likely stems from me misunderstanding what you asked
about. I overlooked you said "modules" and assumed you were talking
about parts of an artifact which otherwise should evolve in a backwards
compatible way.
If a whole artifact is not considered something that is there for public
consumption as an API then I'd just say so (inside the POM, in javadocs,
on the website ...) and not care for backwards compatibility at all.
IMHO we don't need any rules for something like this, proper
documentaton should be enough.
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [All] Convention for "courtesy" codes?
Posted by Gilles <gi...@harfang.homelinux.org>.
On Sat, 10 Feb 2018 08:08:12 -0700, Gary Gregory wrote:
> If a Java package and artifact ID contain "internal" or "private" in
> the
> name, that would be pretty clear.
Do you suggest that, say, the benchmarking codes in
"commons-rng-jmh" should be located in a top package
named "o.a.c.rng.jmh.internal"?
If all codes in a module are internal, it is redundant.
As I've written, it is pretty clear that "examples" or
"benchmarks" are not part of the "library".
What I'm asking is how to convey that <some_module>
should not be limited in its evolution (through
successive versions) by JAR hell considerations,
or Clirr errors.
Gilles
>
> Gary
>
> On Feb 10, 2018 07:17, "Stefan Bodewig" <bo...@apache.org> wrote:
>
>> On 2018-02-10, Gilles wrote:
>>
>> > Is there a convention for distinguishing codes with
>> > compatibility requirements from codes provided as
>> > development tools (unit tests, benchmarking, usage
>> > examples, integration tests, ...)?
>>
>> In Compress we once had a package named _internal_ and a package
>> level
>> javadoc that said "This package is not part of Commons Compress'
>> published API."
>>
>> http://commons.apache.org/proper/commons-compress/
>> javadocs/api-1.7/org/apache/commons/compress/compressors/
>> z/_internal_/package-summary.html
>>
>> There also is a package that says "Experimental" in its javadocs,
>> but to
>> be honest it hasn't change din years (but likely isn't really used
>> by
>> anybody either).
>>
>> Stefan
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [All] Convention for "courtesy" codes?
Posted by Gary Gregory <ga...@gmail.com>.
If a Java package and artifact ID contain "internal" or "private" in the
name, that would be pretty clear.
Gary
On Feb 10, 2018 07:17, "Stefan Bodewig" <bo...@apache.org> wrote:
> On 2018-02-10, Gilles wrote:
>
> > Is there a convention for distinguishing codes with
> > compatibility requirements from codes provided as
> > development tools (unit tests, benchmarking, usage
> > examples, integration tests, ...)?
>
> In Compress we once had a package named _internal_ and a package level
> javadoc that said "This package is not part of Commons Compress'
> published API."
>
> http://commons.apache.org/proper/commons-compress/
> javadocs/api-1.7/org/apache/commons/compress/compressors/
> z/_internal_/package-summary.html
>
> There also is a package that says "Experimental" in its javadocs, but to
> be honest it hasn't change din years (but likely isn't really used by
> anybody either).
>
> Stefan
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [All] Convention for "courtesy" codes?
Posted by Stefan Bodewig <bo...@apache.org>.
On 2018-02-10, Gilles wrote:
> Is there a convention for distinguishing codes with
> compatibility requirements from codes provided as
> development tools (unit tests, benchmarking, usage
> examples, integration tests, ...)?
In Compress we once had a package named _internal_ and a package level
javadoc that said "This package is not part of Commons Compress'
published API."
http://commons.apache.org/proper/commons-compress/javadocs/api-1.7/org/apache/commons/compress/compressors/z/_internal_/package-summary.html
There also is a package that says "Experimental" in its javadocs, but to
be honest it hasn't change din years (but likely isn't really used by
anybody either).
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org