Jakarta-ize JMS Specification document #266

OndroMih · 2020-03-23T11:37:26Z

A subtask of #255.

Update Java EE specification documents to represent Jakarta EE instead of Java EE.

The original specification document uploaded here: messaging.zip (donated and approved in the CQ 21463 .

It should be converted and added in the spec directory here: https://github.com/eclipse-ee4j/jms-api/tree/master/spec. There's now only a stub specification that needs to be replaced.

Some helpful instructions

Instructions from the Jakarta Specification Committee
more information in this Google document - gathers resources by individual projects and the community

Examples of how the Batch spec project converted their spec

The converted Batch spec is here: https://github.com/eclipse-ee4j/batch-api/tree/master/spec/src/main/asciidoc

Related pull requests with comments of what was changed:

I suggest that you don't commit generated PDF and HTML files, I suspect they were committed in the Batch project by accident.

tivrfoa · 2020-03-24T12:53:43Z

Hi,

I created the branch:
https://github.com/tivrfoa/jms-api/tree/initial-spec-doc-contribution

Do you want me to do a pull request only when finished?

tivrfoa · 2020-03-24T13:22:55Z

Examples of how the Batch spec project converted their spec

The converted Batch spec is here: https://github.com/eclipse-ee4j/batch-api/tree/master/spec/src/main/asciidoc

Related pull requests with comments of what was changed:
* [eclipse-ee4j/batch-api#6](https://github.com/eclipse-ee4j/batch-api/pull/6)

* [eclipse-ee4j/batch-api#11](https://github.com/eclipse-ee4j/batch-api/pull/11)

The batch-api repo has in the header:
"Copyright 2012, 2020 International Business Machines Corp."
Is that right?

What text should be instead of the below?

/*
 * Copyright (c) 2011, 2017 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

tivrfoa · 2020-03-24T14:47:47Z

Update Java EE specification documents to represent Jakarta EE instead of Java EE.

The original specification document uploaded here: messaging.zip (donated and approved in the CQ 21463 .

So, the file messaging.zip has two doc files:

Messaging.docx
Messaging21.docx

Should I consider them, or only src/main/asciidoc/Messaging.adoc? What are we targeting?

keilw · 2020-03-25T09:42:18Z

Since Oracle is not the current project lead here any more, I assume Tomitribe shall be mentioned as well, but at least based on my experience as Spec and Maintenance Lead it could have to be both being mentioned in headers or elsewhere.

OndroMih · 2020-03-25T10:47:50Z

To me, it seems that the docx documents are the original JMS documents, which were then converted by Oracle to asciidoc and both versions were donated. I think that we can ignore the docx documents and only work with the asciidoc version, but I'd like to have a confirmation from @kwsutter , @dblevins or @m0mus.

tivrfoa · 2020-03-25T12:36:16Z

Will any of the packages below also move to jakarta? Do I need to change these references in the spec, eg, jakarta.inject?

javax.naming
javax.transaction
javax.inject
javax.jndi

m0mus · 2020-03-25T18:10:43Z

I think you must work with the asciidoc version provided by Eclipse. I'm asking @bshannon for additional confirmation.

bshannon · 2020-03-25T20:00:18Z

@OndroMih is right, all except the asciidoc versions are just there "for reference"
when the contribution was made to Eclipse. They should not be included in the
specification repository. If you already have them there, please remove them.

kwsutter · 2020-03-30T18:13:37Z

Sorry that I missed this conversation, but I agree with @bshannon and @m0mus. Only the asciidoc files and any associated image files should be used. The rest of them should be removed.

tivrfoa · 2020-03-31T16:23:33Z

Hi,

So I need feedback in order to continue:

what to fix?
what else to do?

I still didn't get a reply regarding the legal header.

Maybe it's good if I do a pull request, so you can get what it's already done?

Regarding the line size, what should be the maximum?
Column 72, then move to other line?

bshannon · 2020-03-31T17:00:32Z

Hi,

So I need feedback in order to continue:
* what to fix?

Fix the asciidoc version, using the guidelines above.

* what else to do?
I still didn't get a reply regarding the legal header.

The header you show above is fine for things like the pom.xml or assembly.xml file.
We are not putting a copyright header on the individual *.adoc files; they're covered
by the top level LICENSE file. The license *.adoc file that goes with the spec should
include at least the Oracle copyright line.

Maybe it's good if I do a pull request, so you can get what it's already done?

Always helpful! But I agree it's better to avoid wasting your time by getting some of
the simple issues resolved first.

Regarding the line size, what should be the maximum?
Column 72, then move to other line?

That works for me! I tend to use 80 as a hard limit. I forget what the coding
guidelines say but they might allow a long line length. I think all the *.adoc
files you're starting with should be using 80 columns as the limit.

tivrfoa · 2020-03-31T17:25:49Z

The header you show above is fine for things like the pom.xml or assembly.xml file.
We are not putting a copyright header on the individual *.adoc files; they're covered
by the top level LICENSE file. The license *.adoc file that goes with the spec should
include at least the Oracle copyright line.

The header I showed above has:
Copyright (c) 2011, 2017 Oracle and/or its affiliates. All rights reserved.

Shouldn't it be:
Copyright (c) 2020 Contributors to the Eclipse Foundation.

Currently, the licenses are as below. Should all years be updated to 2020?

assembly.xml and pom.xml:

Copyright (c) 2019 Contributors to the Eclipse Foundation.
license-efsl.adoc:

Copyright (c) 2019 Eclipse Foundation.

also, the "notice" is:
Copyright (c) 2018 Eclipse Foundation.
messaging-spec.adoc:

Copyright (c) 2017, 2019 Contributors to the Eclipse Foundation

bshannon · 2020-03-31T17:33:23Z

The header I showed above has:
Copyright (c) 2011, 2017 Oracle and/or its affiliates. All rights reserved.

Shouldn't it be:
Copyright (c) 2020 Contributors to the Eclipse Foundation.

No, it should not. Oracle copyright headers should not be changed other than
updating the date.

Currently, the licenses are as below. Should all years be updated to 2020?
* assembly.xml and pom.xml:
  Copyright (c) 2019 Contributors to the Eclipse Foundation.

Those were contributed by Oracle and should retain the Oracle copyright, unless
someone rewrote them from scratch.

And yes, the date should be updated to include 2020 as the ending date, e.g.,
"2019, 2020".

* license-efsl.adoc:
  Copyright (c) 2019 Eclipse Foundation.
  also, the "notice" is:
  Copyright (c) 2018 Eclipse Foundation.

You're right, I was wrong, the spec license file should have copyright Eclipse.

* messaging-spec.adoc:
  Copyright (c) 2017, 2019 Contributors to the Eclipse Foundation

I believe that was written from scratch so the Eclipse copyright is fine, although
again we in general haven't been putting copyright notices in the individual *.adoc
files. The complication that can make things confusing is that the spec source
files are licensed under EPL (with no GPL/CE) but the output of the spec generation
process is licensed under the Eclipse Foundation Specification License (EFSL).

keilw · 2020-03-31T17:37:57Z

No it certainly never will be "Copyright Contributors to the Eclipse Foundation" or "Copyright Eclipse Foundation". Take other specs like Batch "Copyright 2012, 2020 International Business Machines Corp."
or

* Copyright 2010, Red Hat, Inc., and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.

in CDI.

keilw · 2020-03-31T17:40:01Z

Well just take @bshannon's input for the specification, although e.g. CDI does not have headers in the ADOC files, therefore it seems reasonable to keep those only in a single LICENCE file.

tivrfoa · 2020-03-31T21:17:05Z

Hi,

I made a pull request for this issue. Not that it's done, but I think it's good for a first contribution, so others can help too:
#267

I used the code below to limit the line size to 72 columns:
https://github.com/tivrfoa/AsciiDoc/blob/master/LimitLineSizeAdoc.java

OndroMih · 2021-05-03T11:51:33Z

Fixed by #275

OndroMih added task help wanted Extra attention is needed good first issue Good for newcomers labels Mar 23, 2020

OndroMih self-assigned this Mar 23, 2020

kwsutter mentioned this issue Mar 23, 2020

Deliver Jakarta Messaging Specification Version update for Jakarta EE 9 #255

Closed

11 tasks

OndroMih mentioned this issue Apr 25, 2020

Initial conversion of the spec document for Jakarta #271

Closed

OndroMih closed this as completed May 3, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Jakarta-ize JMS Specification document #266

Jakarta-ize JMS Specification document #266

OndroMih commented Mar 23, 2020 •

edited

Loading

tivrfoa commented Mar 24, 2020

tivrfoa commented Mar 24, 2020

Examples of how the Batch spec project converted their spec

tivrfoa commented Mar 24, 2020

keilw commented Mar 25, 2020 •

edited

Loading

OndroMih commented Mar 25, 2020

tivrfoa commented Mar 25, 2020

m0mus commented Mar 25, 2020 •

edited

Loading

bshannon commented Mar 25, 2020

kwsutter commented Mar 30, 2020

tivrfoa commented Mar 31, 2020

bshannon commented Mar 31, 2020 •

edited

Loading

tivrfoa commented Mar 31, 2020

bshannon commented Mar 31, 2020 •

edited

Loading

keilw commented Mar 31, 2020 •

edited

Loading

keilw commented Mar 31, 2020

tivrfoa commented Mar 31, 2020

OndroMih commented May 3, 2021

Jakarta-ize JMS Specification document #266

Jakarta-ize JMS Specification document #266

Comments

OndroMih commented Mar 23, 2020 • edited Loading

Some helpful instructions

Examples of how the Batch spec project converted their spec

tivrfoa commented Mar 24, 2020

tivrfoa commented Mar 24, 2020

Examples of how the Batch spec project converted their spec

tivrfoa commented Mar 24, 2020

keilw commented Mar 25, 2020 • edited Loading

OndroMih commented Mar 25, 2020

tivrfoa commented Mar 25, 2020

m0mus commented Mar 25, 2020 • edited Loading

bshannon commented Mar 25, 2020

kwsutter commented Mar 30, 2020

tivrfoa commented Mar 31, 2020

bshannon commented Mar 31, 2020 • edited Loading

tivrfoa commented Mar 31, 2020

bshannon commented Mar 31, 2020 • edited Loading

keilw commented Mar 31, 2020 • edited Loading

keilw commented Mar 31, 2020

tivrfoa commented Mar 31, 2020

OndroMih commented May 3, 2021

OndroMih commented Mar 23, 2020 •

edited

Loading

keilw commented Mar 25, 2020 •

edited

Loading

m0mus commented Mar 25, 2020 •

edited

Loading

bshannon commented Mar 31, 2020 •

edited

Loading

bshannon commented Mar 31, 2020 •

edited

Loading

keilw commented Mar 31, 2020 •

edited

Loading