[All] Convention for "courtesy" codes?

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

[All] Convention for "courtesy" codes?

Gilles Sadowski
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [All] Convention for "courtesy" codes?

Stefan Bodewig
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [All] Convention for "courtesy" codes?

garydgregory
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" <[hidden email]> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [All] Convention for "courtesy" codes?

Gilles Sadowski
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" <[hidden email]> 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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [All] Convention for "courtesy" codes?

Stefan Bodewig
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [All] Convention for "courtesy" codes?

Gilles Sadowski
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [All] Convention for "courtesy" codes?

Gilles Sadowski
In reply to this post by Stefan Bodewig
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: [hidden email]
For additional commands, e-mail: [hidden email]