Jakarta-ize JMS Specification document

OndroMih commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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)

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

bshannon commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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.

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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: https://github.com/eclipse-ee4j/jms-api/pull/267

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

OndroMih commented 3 years ago

Fixed by https://github.com/eclipse-ee4j/jms-api/pull/275

jakartaee / messaging