Closed OndroMih closed 3 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?
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
*/
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:
Should I consider them, or only src/main/asciidoc/Messaging.adoc? What are we targeting?
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.
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.
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
I think you must work with the asciidoc
version provided by Eclipse. I'm asking @bshannon for additional confirmation.
@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.
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.
Hi,
So I need feedback in order to continue:
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?
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.
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
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).
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.
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.
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
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
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.