From jwilhelm at openjdk.java.net  Tue Jun  2 01:27:03 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 2 Jun 2020 01:27:03 GMT
Subject: RFR: Updated intro
Message-ID: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>

I re-wrote the intro to talk more about the present and less about the past.

-------------

Commit messages:
 - Updated intro

Changes: https://git.openjdk.java.net/guide/pull/15/files
 Webrev: https://webrevs.openjdk.java.net/guide/15/webrev.00
  Stats: 39 lines in 2 files changed: 32 ins; 4 del; 3 mod
  Patch: https://git.openjdk.java.net/guide/pull/15.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/15/head:pull/15

PR: https://git.openjdk.java.net/guide/pull/15

From iris at openjdk.java.net  Tue Jun  2 06:47:32 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Tue, 2 Jun 2020 06:47:32 GMT
Subject: RFR: Updated intro
In-Reply-To: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
Message-ID: <FKp688cyjfBi5wVLB74sKpCVoCoMupYCqgmrvtY4MRU=.0ecbcd8d-01ae-422f-a09a-68c6bd2a676a@github.com>

On Tue, 2 Jun 2020 01:20:59 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> I re-wrote the intro to talk more about the present and less about the past.

src/intro.md line 9:

> 8:
> 9: The OpejJDK project governs the Java programming language and the Java runtime.
> 10: The project was created when the JDK was first released under the GPLv2 license in May

Not quite.  The Java APIs, JLS, JVMS, and other normative specifications (e.g. Serialization Spec, RMI Spec, etc.) are
defined by the Java Community Process (jcp.org).  OpenJDK is the place to collaborate on an open-source implementation
of the Java Platform, Standard Edition, and related projects.

src/intro.md line 10:

> 9: The OpejJDK project governs the Java programming language and the Java runtime.
> 10: The project was created when the JDK was first released under the GPLv2 license in May
> 11: 2007 and since then a community has grown around it to help develop and maintain Java.

I think that "The project" should be replaced with "OpenJDK".

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From ihse at openjdk.java.net  Tue Jun  2 09:42:37 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Tue, 2 Jun 2020 09:42:37 GMT
Subject: RFR: Updated intro
In-Reply-To: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
Message-ID: <20e6VBKsmAObi6ufp8pj3voEnXoibVscnMfN2mq1Ht8=.c0045684-1bb8-4344-8c72-86c2a39d7470@github.com>

On Tue, 2 Jun 2020 01:20:59 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> I re-wrote the intro to talk more about the present and less about the past.

Changes requested by ihse (no project role).

src/intro.md line 32:

> 31:
> 32: ## Maintenance
> 33:

A "Maintenance" heading in the intro sounds like maintenance on OpenJDK itself.

The maintenance on the guide itself is rather un-interesting. Maybe you should add a trailing chapter "About this
Guide" or something like that, where you can put stuff like that.

src/intro.md line 9:

> 8:
> 9: The OpejJDK project governs the Java programming language and the Java runtime.
> 10: The project was created when the JDK was first released under the GPLv2 license in May

Typo "Opej".

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Tue Jun  2 19:52:12 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 2 Jun 2020 19:52:12 GMT
Subject: [Rev 01] RFR: Updated intro
In-Reply-To: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
Message-ID: <GH7FWcY3SWCWTaLzPJAnzatPpdRl8j_ohYQm_lUcKQU=.0ecb8d54-bc1a-4286-8422-955c045889f8@github.com>

> I re-wrote the intro to talk more about the present and less about the past.

Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:

  Changes after review

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/15/files
  - new: https://git.openjdk.java.net/guide/pull/15/files/20cb59cb..f3d00ffe

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/15/webrev.01
 - incr: https://webrevs.openjdk.java.net/guide/15/webrev.00-01

  Stats: 37 lines in 5 files changed: 20 ins; 11 del; 6 mod
  Patch: https://git.openjdk.java.net/guide/pull/15.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/15/head:pull/15

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Tue Jun  2 20:01:40 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 2 Jun 2020 20:01:40 GMT
Subject: [Rev 01] RFR: Updated intro
In-Reply-To: <FKp688cyjfBi5wVLB74sKpCVoCoMupYCqgmrvtY4MRU=.0ecbcd8d-01ae-422f-a09a-68c6bd2a676a@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
 <FKp688cyjfBi5wVLB74sKpCVoCoMupYCqgmrvtY4MRU=.0ecbcd8d-01ae-422f-a09a-68c6bd2a676a@github.com>
Message-ID: <B56csemoYxU2N3JzSs0K8rzy5neXfXmYpEU6xFxqf98=.40680af7-ee27-404a-8196-707b709d7625@github.com>

On Tue, 2 Jun 2020 06:42:56 GMT, Iris Clark <iris at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Changes after review
>
> src/intro.md line 9:
> 
>> 8:
>> 9: The OpejJDK project governs the Java programming language and the Java runtime.
>> 10: The project was created when the JDK was first released under the GPLv2 license in May
> 
> Not quite.  The Java APIs, JLS, JVMS, and other normative specifications (e.g. Serialization Spec, RMI Spec, etc.) are
> defined by the Java Community Process (jcp.org).  OpenJDK is the place to collaborate on an open-source implementation
> of the Java Platform, Standard Edition, and related projects.

Right. I'll take that sentence :-)

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Tue Jun  2 20:01:41 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 2 Jun 2020 20:01:41 GMT
Subject: [Rev 01] RFR: Updated intro
In-Reply-To: <20e6VBKsmAObi6ufp8pj3voEnXoibVscnMfN2mq1Ht8=.c0045684-1bb8-4344-8c72-86c2a39d7470@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
 <20e6VBKsmAObi6ufp8pj3voEnXoibVscnMfN2mq1Ht8=.c0045684-1bb8-4344-8c72-86c2a39d7470@github.com>
Message-ID: <ZHYjL6RyYkLoHDNuHO_SYXnk4yA8v4A_ceZM-ys9lPg=.5a4d2ff1-b5f8-4e3d-92e6-bab911443dc3@github.com>

On Tue, 2 Jun 2020 09:38:29 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Changes after review
>
> src/intro.md line 32:
> 
>> 31:
>> 32: ## Maintenance
>> 33:
> 
> A "Maintenance" heading in the intro sounds like maintenance on OpenJDK itself.
> 
> The maintenance on the guide itself is rather un-interesting. Maybe you should add a trailing chapter "About this
> Guide" or something like that, where you can put stuff like that.

Agreed. A new chapter added for the about stuff.

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From ihse at openjdk.java.net  Tue Jun  2 20:42:17 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Tue, 2 Jun 2020 20:42:17 GMT
Subject: [Rev 01] RFR: Updated intro
In-Reply-To: <GH7FWcY3SWCWTaLzPJAnzatPpdRl8j_ohYQm_lUcKQU=.0ecb8d54-bc1a-4286-8422-955c045889f8@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
 <GH7FWcY3SWCWTaLzPJAnzatPpdRl8j_ohYQm_lUcKQU=.0ecb8d54-bc1a-4286-8422-955c045889f8@github.com>
Message-ID: <sySITSxyUaWrLQFiBtlGLV28zAY_EgTMtkWzDtmPpzI=.62ba7cb4-9675-4795-afc4-4a55c8880c45@github.com>

On Tue, 2 Jun 2020 19:52:12 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> I re-wrote the intro to talk more about the present and less about the past.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Changes after review

src/index.md line 8:

> 7: * [Introduction](intro.html)
> 8:   * [Maintenance](intro.html#maintenance)
> 9: * [Process Workflow](processWorkflow.html)

Don't think this should be here anymore.

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Tue Jun  2 20:58:41 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 2 Jun 2020 20:58:41 GMT
Subject: [Rev 02] RFR: Updated intro
In-Reply-To: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
Message-ID: <Q0qCUHjF7KnGvpmFgbPko5O3l5jd1Tjj5Asmlck3v9w=.a8fee190-7fb7-4db7-9830-3ca2df79f14c@github.com>

> I re-wrote the intro to talk more about the present and less about the past.

Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:

  Removed Maintenance

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/15/files
  - new: https://git.openjdk.java.net/guide/pull/15/files/f3d00ffe..c2e69651

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/15/webrev.02
 - incr: https://webrevs.openjdk.java.net/guide/15/webrev.01-02

  Stats: 1 line in 1 file changed: 0 ins; 1 del; 0 mod
  Patch: https://git.openjdk.java.net/guide/pull/15.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/15/head:pull/15

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Tue Jun  2 21:07:11 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 2 Jun 2020 21:07:11 GMT
Subject: [Rev 01] RFR: Updated intro
In-Reply-To: <sySITSxyUaWrLQFiBtlGLV28zAY_EgTMtkWzDtmPpzI=.62ba7cb4-9675-4795-afc4-4a55c8880c45@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
 <GH7FWcY3SWCWTaLzPJAnzatPpdRl8j_ohYQm_lUcKQU=.0ecb8d54-bc1a-4286-8422-955c045889f8@github.com>
 <sySITSxyUaWrLQFiBtlGLV28zAY_EgTMtkWzDtmPpzI=.62ba7cb4-9675-4795-afc4-4a55c8880c45@github.com>
Message-ID: <juRcWUV51YPEymF_shsR2LHWuFW87XD6VGrxvTr39mw=.194ead7a-1ae2-4528-87e8-bcac1641660e@github.com>

On Tue, 2 Jun 2020 20:39:58 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Changes after review
>
> src/index.md line 8:
> 
>> 7: * [Introduction](intro.html)
>> 8:   * [Maintenance](intro.html#maintenance)
>> 9: * [Process Workflow](processWorkflow.html)
> 
> Don't think this should be here anymore.

Doh.. Fixed, and fixed again. I wrote a script to generate the index automatically at make time, that should avoid
these issues in the future. A few corner cases that needs to be fixed before I push that though.

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Tue Jun  2 21:07:10 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Tue, 2 Jun 2020 21:07:10 GMT
Subject: [Rev 03] RFR: Updated intro
In-Reply-To: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
Message-ID: <9NqTIORBaGE1amnuVbWQ7T_jS4peti5VegK157bv9x0=.920c2f9b-98e7-45e5-8aad-2956a9c8847b@github.com>

> I re-wrote the intro to talk more about the present and less about the past.

Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:

  Fixed more index

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/15/files
  - new: https://git.openjdk.java.net/guide/pull/15/files/c2e69651..23aa75d9

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/15/webrev.03
 - incr: https://webrevs.openjdk.java.net/guide/15/webrev.02-03

  Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.java.net/guide/pull/15.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/15/head:pull/15

PR: https://git.openjdk.java.net/guide/pull/15

From ihse at openjdk.java.net  Wed Jun  3 10:17:22 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Wed, 3 Jun 2020 10:17:22 GMT
Subject: [Rev 03] RFR: Updated intro
In-Reply-To: <9NqTIORBaGE1amnuVbWQ7T_jS4peti5VegK157bv9x0=.920c2f9b-98e7-45e5-8aad-2956a9c8847b@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
 <9NqTIORBaGE1amnuVbWQ7T_jS4peti5VegK157bv9x0=.920c2f9b-98e7-45e5-8aad-2956a9c8847b@github.com>
Message-ID: <C8HfLO9gczTJsMo1NG1M6oRNXarTkExpI70KcrIBNXQ=.a47fbaf9-1ce9-4b00-83d4-083e489bf405@github.com>

On Tue, 2 Jun 2020 21:07:10 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> I re-wrote the intro to talk more about the present and less about the past.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fixed more index

Marked as reviewed by ihse (no project role).

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Wed Jun  3 17:19:16 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Wed, 3 Jun 2020 17:19:16 GMT
Subject: RFR: Added anchor for noreg table
Message-ID: <B15fRIsznDtoEWPCzEvWETrYmSMLMHbQDmOgju8zI5Q=.0a35b1ed-fed9-45ba-be08-368035ff3964@github.com>

On request, adding an anchor to allow for links to the noreg-table. The link will be
https://openjdk.java.net/guide/changePlanning.html#noreg

-------------

Commit messages:
 - Fixed an unrelated typo on the same page
 - Added anchor for noreg table

Changes: https://git.openjdk.java.net/guide/pull/16/files
 Webrev: https://webrevs.openjdk.java.net/guide/16/webrev.00
  Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.java.net/guide/pull/16.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/16/head:pull/16

PR: https://git.openjdk.java.net/guide/pull/16

From iris at openjdk.java.net  Wed Jun  3 18:12:06 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Wed, 3 Jun 2020 18:12:06 GMT
Subject: [Rev 03] RFR: Updated intro
In-Reply-To: <9NqTIORBaGE1amnuVbWQ7T_jS4peti5VegK157bv9x0=.920c2f9b-98e7-45e5-8aad-2956a9c8847b@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
 <9NqTIORBaGE1amnuVbWQ7T_jS4peti5VegK157bv9x0=.920c2f9b-98e7-45e5-8aad-2956a9c8847b@github.com>
Message-ID: <H01m_PdXq1I05J45FDhj8sPx-XW41wL9lZOCfobXLdc=.c8a32587-eab0-440a-9e92-9163b3d8a6b8@github.com>

On Tue, 2 Jun 2020 21:07:10 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> I re-wrote the intro to talk more about the present and less about the past.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fixed more index

Looks good!

-------------

Marked as reviewed by iris (Reviewer).

PR: https://git.openjdk.java.net/guide/pull/15

From iris at openjdk.java.net  Wed Jun  3 18:23:52 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Wed, 3 Jun 2020 18:23:52 GMT
Subject: RFR: Added anchor for noreg table
In-Reply-To: <B15fRIsznDtoEWPCzEvWETrYmSMLMHbQDmOgju8zI5Q=.0a35b1ed-fed9-45ba-be08-368035ff3964@github.com>
References: <B15fRIsznDtoEWPCzEvWETrYmSMLMHbQDmOgju8zI5Q=.0a35b1ed-fed9-45ba-be08-368035ff3964@github.com>
Message-ID: <j8kE4CNrYKqLGonYVbSHqrMslavVz1hSVCfnj5JdbN8=.705aa6ee-922c-4bd2-86fd-af8b4d8251b6@github.com>

On Wed, 3 Jun 2020 17:09:44 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> On request, adding an anchor to allow for links to the noreg-table. The link will be
> https://openjdk.java.net/guide/changePlanning.html#noreg

Thanks for the link.

-------------

Marked as reviewed by iris (Reviewer).

PR: https://git.openjdk.java.net/guide/pull/16

From jwilhelm at openjdk.java.net  Wed Jun  3 18:24:06 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Wed, 3 Jun 2020 18:24:06 GMT
Subject: [Rev 03] RFR: Updated intro
In-Reply-To: <H01m_PdXq1I05J45FDhj8sPx-XW41wL9lZOCfobXLdc=.c8a32587-eab0-440a-9e92-9163b3d8a6b8@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
 <9NqTIORBaGE1amnuVbWQ7T_jS4peti5VegK157bv9x0=.920c2f9b-98e7-45e5-8aad-2956a9c8847b@github.com>
 <H01m_PdXq1I05J45FDhj8sPx-XW41wL9lZOCfobXLdc=.c8a32587-eab0-440a-9e92-9163b3d8a6b8@github.com>
Message-ID: <S-XnzDBglq0xxDZyieNpsMtuIh7UQO02QFsGT_wV5F4=.f59d60e6-f6d5-4b85-87e0-70dd665e9c59@github.com>

On Wed, 3 Jun 2020 18:09:58 GMT, Iris Clark <iris at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fixed more index
>
> Looks good!

Thank you all for reviewing!

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Wed Jun  3 18:24:07 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Wed, 3 Jun 2020 18:24:07 GMT
Subject: [Integrated] RFR: Updated intro
In-Reply-To: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
References: <RONhZ4GluCbZiEgpyLbkarlLAKCF1zcl8nNbXinOsmg=.24c93bad-f041-46c9-a1bc-806acf275c12@github.com>
Message-ID: <EIBqM-8P4evq518TFSz9hQU7yHXZszrNSNfziqpqN8Q=.3a4df908-0e5b-43a0-b602-5d1d795e1dd0@github.com>

On Tue, 2 Jun 2020 01:20:59 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> I re-wrote the intro to talk more about the present and less about the past.

This pull request has now been integrated.

Changeset: bf0e582e
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/guide/commit/bf0e582e
Stats:     52 lines in 5 files changed: 5 ins; 41 del; 6 mod

Updated intro

Reviewed-by: ihse, iris

-------------

PR: https://git.openjdk.java.net/guide/pull/15

From jwilhelm at openjdk.java.net  Wed Jun  3 19:12:35 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Wed, 3 Jun 2020 19:12:35 GMT
Subject: [Integrated] RFR: Added anchor for noreg table
In-Reply-To: <B15fRIsznDtoEWPCzEvWETrYmSMLMHbQDmOgju8zI5Q=.0a35b1ed-fed9-45ba-be08-368035ff3964@github.com>
References: <B15fRIsznDtoEWPCzEvWETrYmSMLMHbQDmOgju8zI5Q=.0a35b1ed-fed9-45ba-be08-368035ff3964@github.com>
Message-ID: <27Fxs3GGJtx5Hsr8DkVQQUaHlb5GIw1t9zqmzNga9DY=.cf898bd9-585b-4566-9e29-13116150cde0@github.com>

On Wed, 3 Jun 2020 17:09:44 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> On request, adding an anchor to allow for links to the noreg-table. The link will be
> https://openjdk.java.net/guide/changePlanning.html#noreg

This pull request has now been integrated.

Changeset: 6f42a959
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/guide/commit/6f42a959
Stats:     2 lines in 1 file changed: 0 ins; 0 del; 2 mod

Added anchor for noreg table

Reviewed-by: iris

-------------

PR: https://git.openjdk.java.net/guide/pull/16

From jwilhelm at openjdk.java.net  Wed Jun 10 23:40:18 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Wed, 10 Jun 2020 23:40:18 GMT
Subject: RFR: New text about mailing lists
Message-ID: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>

The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
lists are used though.

-------------

Commit messages:
 - New text about mailing lists

Changes: https://git.openjdk.java.net/guide/pull/17/files
 Webrev: https://webrevs.openjdk.java.net/guide/17/webrev.00
  Stats: 60 lines in 2 files changed: 49 ins; 7 del; 4 mod
  Patch: https://git.openjdk.java.net/guide/pull/17.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/17/head:pull/17

PR: https://git.openjdk.java.net/guide/pull/17

From david.holmes at oracle.com  Thu Jun 11 04:28:54 2020
From: david.holmes at oracle.com (David Holmes)
Date: Thu, 11 Jun 2020 14:28:54 +1000
Subject: RFR: New text about mailing lists
In-Reply-To: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
Message-ID: <e363701c-9e02-bcf9-eb84-c9ed7c4bbaea@oracle.com>

Hi Jesper,

On 11/06/2020 9:40 am, Jesper Wilhelmsson wrote:
> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
> lists are used though.

The -experts list is not necessarily moderated but it is restricted; 
only members of the expert group can subscribe to that list. The 
-observers list is for anyone to subscribe to see what the experts are 
discussing and potentially to have some dialog with other non-experts. 
There is no guarantee that an expert is subscribed to the observer list 
or will see any responses on that list. The -comments list is for 
observers to directly provide feedback/comments to the experts 
(typically a lead will process the comments list and forward things on 
to the experts list).

+ speak other languages as their mother tongue.

"mother tongue" is itself a phrase that may cause confusion to 
non-native English speakers. :) I suggest "native language".

--

      --- 
-----------------------------------------------------------------------
!     Y   Submission of a CSR request is required. Work may begin after the
!         request has been [accepted](glossary.html#accepted) by the 
CSR; the
           changeset implementing the fix may be committed to a team forest
!         after the request has been [approved](glossary.html#approved) 
by the CSR.
!         A description of the CSR requirements may be found in
           [Review Bodies](reviewBodies.html).

This text seems quite dated and not fully applicable to the CSR process. 
I would suggest using the same language as used on the CSR wiki. We 
don't have an "acceptance" phase for CSR requests - work typically 
begins in parallel with the CSR request, or often before.  "team forest" 
is a generally out-dated term - I would just say "repository".

Thanks,
David
-----

> -------------
> 
> Commit messages:
>   - New text about mailing lists
> 
> Changes: https://git.openjdk.java.net/guide/pull/17/files
>   Webrev: https://webrevs.openjdk.java.net/guide/17/webrev.00
>    Stats: 60 lines in 2 files changed: 49 ins; 7 del; 4 mod
>    Patch: https://git.openjdk.java.net/guide/pull/17.diff
>    Fetch: git fetch https://git.openjdk.java.net/guide pull/17/head:pull/17
> 
> PR: https://git.openjdk.java.net/guide/pull/17
> 

From iris.clark at oracle.com  Thu Jun 11 07:50:26 2020
From: iris.clark at oracle.com (Iris Clark)
Date: Thu, 11 Jun 2020 00:50:26 -0700 (PDT)
Subject: RFR: New text about mailing lists
In-Reply-To: <e363701c-9e02-bcf9-eb84-c9ed7c4bbaea@oracle.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
 <e363701c-9e02-bcf9-eb84-c9ed7c4bbaea@oracle.com>
Message-ID: <159b9fef-8b79-4e14-b1d6-12745e751b9b@default>

Hi, Jesper.

David's description of the "-experts", "-observers" and "-comments" lists is correct.  This trio of lists was originally designed as an option for Projects implementing JSRs.  This page contains the descriptions of these lists for the Platform JSRs:

    https://openjdk.java.net/projects/jdk/16/spec/

Thanks,
Iris

-----Original Message-----
From: David Holmes 
Sent: Wednesday, June 10, 2020 9:29 PM
To: Jesper Wilhelmsson <jwilhelm at openjdk.java.net>; guide-dev at openjdk.java.net
Subject: Re: RFR: New text about mailing lists

Hi Jesper,

On 11/06/2020 9:40 am, Jesper Wilhelmsson wrote:
> The last three types of lists, used for expert groups, could use a 
> better explanation. I'm not sure how these types of lists are used though.

The -experts list is not necessarily moderated but it is restricted; only members of the expert group can subscribe to that list. The -observers list is for anyone to subscribe to see what the experts are discussing and potentially to have some dialog with other non-experts. 
There is no guarantee that an expert is subscribed to the observer list or will see any responses on that list. The -comments list is for observers to directly provide feedback/comments to the experts (typically a lead will process the comments list and forward things on to the experts list).

+ speak other languages as their mother tongue.

"mother tongue" is itself a phrase that may cause confusion to non-native English speakers. :) I suggest "native language".

--

      ---
-----------------------------------------------------------------------
!     Y   Submission of a CSR request is required. Work may begin after the
!         request has been [accepted](glossary.html#accepted) by the 
CSR; the
           changeset implementing the fix may be committed to a team forest
!         after the request has been [approved](glossary.html#approved) 
by the CSR.
!         A description of the CSR requirements may be found in
           [Review Bodies](reviewBodies.html).

This text seems quite dated and not fully applicable to the CSR process. 
I would suggest using the same language as used on the CSR wiki. We don't have an "acceptance" phase for CSR requests - work typically begins in parallel with the CSR request, or often before.  "team forest" 
is a generally out-dated term - I would just say "repository".

Thanks,
David
-----

> -------------
> 
> Commit messages:
>   - New text about mailing lists
> 
> Changes: https://git.openjdk.java.net/guide/pull/17/files
>   Webrev: https://webrevs.openjdk.java.net/guide/17/webrev.00
>    Stats: 60 lines in 2 files changed: 49 ins; 7 del; 4 mod
>    Patch: https://git.openjdk.java.net/guide/pull/17.diff
>    Fetch: git fetch https://git.openjdk.java.net/guide 
> pull/17/head:pull/17
> 
> PR: https://git.openjdk.java.net/guide/pull/17
> 

From jwilhelm at openjdk.java.net  Thu Jun 11 21:20:57 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 11 Jun 2020 21:20:57 GMT
Subject: [Rev 01] RFR: New text about mailing lists
In-Reply-To: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
Message-ID: <GiFDUv-M18wfFs6KcOzRZpufEj0d_BbJMK4nGih6rFo=.d8223cbc-65ce-4212-a231-9d40a2ebbd97@github.com>

> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
> lists are used though.

Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:

  Updates after review

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/17/files
  - new: https://git.openjdk.java.net/guide/pull/17/files/311fdc5b..96173f56

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/17/webrev.01
 - incr: https://webrevs.openjdk.java.net/guide/17/webrev.00-01

  Stats: 12 lines in 1 file changed: 5 ins; 3 del; 4 mod
  Patch: https://git.openjdk.java.net/guide/pull/17.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/17/head:pull/17

PR: https://git.openjdk.java.net/guide/pull/17

From jwilhelm at openjdk.java.net  Thu Jun 11 21:33:39 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 11 Jun 2020 21:33:39 GMT
Subject: RFR: New text about mailing lists
In-Reply-To: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
Message-ID: <0rbEn4v7v9X-VCRk0l3Eok_ePyaVKGduqHkpmSfCl7o=.b0eb1bc9-7c16-4da0-9daf-57c010d25967@github.com>

On Wed, 10 Jun 2020 23:30:21 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
> lists are used though.

Thanks for the reviews!

David, I've used most of your wording for the list descriptions. I'll ask Joe to take a look at the CSR description.

-------------

PR: https://git.openjdk.java.net/guide/pull/17

From david.holmes at oracle.com  Thu Jun 11 23:26:51 2020
From: david.holmes at oracle.com (David Holmes)
Date: Fri, 12 Jun 2020 09:26:51 +1000
Subject: [Rev 01] RFR: New text about mailing lists
In-Reply-To: <GiFDUv-M18wfFs6KcOzRZpufEj0d_BbJMK4nGih6rFo=.d8223cbc-65ce-4212-a231-9d40a2ebbd97@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
 <GiFDUv-M18wfFs6KcOzRZpufEj0d_BbJMK4nGih6rFo=.d8223cbc-65ce-4212-a231-9d40a2ebbd97@github.com>
Message-ID: <0f8d303b-1ae5-3e29-2972-3423a5849468@oracle.com>

Hi Jesper,

A couple of follow up comments.

On 12/06/2020 7:20 am, Jesper Wilhelmsson wrote:
>> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
>> lists are used though.
> 
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>    Updates after review
> 
> -------------
> 
> Changes:
>    - all: https://git.openjdk.java.net/guide/pull/17/files
>    - new: https://git.openjdk.java.net/guide/pull/17/files/311fdc5b..96173f56
> 
> Webrevs:
>   - full: https://webrevs.openjdk.java.net/guide/17/webrev.01
>   - incr: https://webrevs.openjdk.java.net/guide/17/webrev.00-01

8 All participation in an OpenJDK project starts with joining the 
project mailing
9 list. All OpenJDK mailing lists are found here:

I would say "joining the relevant mailing lists" as not all lists are 
obviously project related - see next point.

24 There are a few different types of lists. The list name has two parts 
to explain what
25 the list is intended for, `<project>-<suffix>`, where the first part 
is the project
26 that owns the list and the second part is explained below.

That is a description of the high-level mailing lists typically created 
for project discussion, but not all mailing lists are like that. We have 
hotspot-dev, hotspot-runtime-dev, hotspot-gc-dev etc etc which do not 
fall into this categorisation. They relate to development primarily in 
the JDK project (but that isn't evident in their name), but they can be 
used in relation to numerous projects.

And not all projects have the full set of lists described (e.g. no 
experts/observers/comments for JDK project or JDK Updates project etc.)

Cheers,
David
-----

>    Stats: 12 lines in 1 file changed: 5 ins; 3 del; 4 mod
>    Patch: https://git.openjdk.java.net/guide/pull/17.diff
>    Fetch: git fetch https://git.openjdk.java.net/guide pull/17/head:pull/17
> 
> PR: https://git.openjdk.java.net/guide/pull/17
> 

From jwilhelm at openjdk.java.net  Fri Jun 12 01:52:47 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Fri, 12 Jun 2020 01:52:47 GMT
Subject: [Rev 02] RFR: New text about mailing lists
In-Reply-To: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
Message-ID: <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>

> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
> lists are used though.

Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:

  Rephrased name-suffix part

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/17/files
  - new: https://git.openjdk.java.net/guide/pull/17/files/96173f56..2319b7a2

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/17/webrev.02
 - incr: https://webrevs.openjdk.java.net/guide/17/webrev.01-02

  Stats: 5 lines in 1 file changed: 2 ins; 0 del; 3 mod
  Patch: https://git.openjdk.java.net/guide/pull/17.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/17/head:pull/17

PR: https://git.openjdk.java.net/guide/pull/17

From david.holmes at oracle.com  Fri Jun 12 04:40:48 2020
From: david.holmes at oracle.com (David Holmes)
Date: Fri, 12 Jun 2020 14:40:48 +1000
Subject: [Rev 02] RFR: New text about mailing lists
In-Reply-To: <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
 <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>
Message-ID: <d2a66735-8d3e-7fff-2359-8933fadf4329@oracle.com>

Looks good!

Thanks,
David

On 12/06/2020 11:52 am, Jesper Wilhelmsson wrote:
>> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
>> lists are used though.
> 
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>    Rephrased name-suffix part
> 
> -------------
> 
> Changes:
>    - all: https://git.openjdk.java.net/guide/pull/17/files
>    - new: https://git.openjdk.java.net/guide/pull/17/files/96173f56..2319b7a2
> 
> Webrevs:
>   - full: https://webrevs.openjdk.java.net/guide/17/webrev.02
>   - incr: https://webrevs.openjdk.java.net/guide/17/webrev.01-02
> 
>    Stats: 5 lines in 1 file changed: 2 ins; 0 del; 3 mod
>    Patch: https://git.openjdk.java.net/guide/pull/17.diff
>    Fetch: git fetch https://git.openjdk.java.net/guide pull/17/head:pull/17
> 
> PR: https://git.openjdk.java.net/guide/pull/17
> 

From ihse at openjdk.java.net  Mon Jun 15 14:56:47 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Mon, 15 Jun 2020 14:56:47 GMT
Subject: [Rev 02] RFR: New text about mailing lists
In-Reply-To: <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
 <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>
Message-ID: <na_2bPsdrtIKsHcyPvBDi7xcfhzhk23NzdBar1-IPOk=.552dd86e-8bc2-4813-809d-faa907abb16a@github.com>

On Fri, 12 Jun 2020 01:52:47 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
>> lists are used though.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Rephrased name-suffix part

Marked as reviewed by ihse (no project role).

-------------

PR: https://git.openjdk.java.net/guide/pull/17

From iris at openjdk.java.net  Wed Jun 17 17:22:02 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Wed, 17 Jun 2020 17:22:02 GMT
Subject: RFR: New text about mailing lists [v3]
In-Reply-To: <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
 <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>
Message-ID: <99MHvct34yDbxeg8DTNGu3PivUZJoP7b8KPcy6symrU=.50350a1c-aeba-4195-8f43-1ffe1e2a2e2f@github.com>

On Fri, 12 Jun 2020 01:52:47 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
>> lists are used though.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Rephrased name-suffix part

Your descriptions look good.

I'm wondering if subscription recommendations should be made for those new to OpenJDK?  Whenever I'm asked, my response
is usually announce, discuss, and the "-dev" list(s?) covering the explicit area of interest.

Random note:  Per the Bylaws, OpenJDK mailing list subscribers are defined as "Participants"
(https://openjdk.java.net/bylaws#participant).

-------------

Marked as reviewed by iris (Reviewer).

PR: https://git.openjdk.java.net/guide/pull/17

From jwilhelm at openjdk.java.net  Thu Jun 18 13:10:23 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 18 Jun 2020 13:10:23 GMT
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
Message-ID: <m69dXE0tCvtbp9Rm0zjvU-gtSrKi-BgbLju24Q9agw0=.f159e3e4-128b-46c2-a189-61a8c722058c@github.com>

On Sun, 31 May 2020 20:14:44 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

> Pull request for adding code conventions.
> 
> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

Thank you for contributing this style guide. This is something that many have been asking about.

src/codeConventions.md line 7:

> 6:
> 7: This is a set of code conventions for for JDK Release Projects in the OpenJDK Community. Other OpenJDK Projects, and
> projects outside of OpenJDK, are welcome to adopt these guidelines as they see fit. 8:

This code convention is for Java code only, right? I'm thinking that we want to have a separate style guide for C++
code, and there will be one for markdown as well since it's used in several places in the docs. For this reason I think
it would be better if the actual style guide was on a separate page and this main style-page only has the Motivation
and Guiding Principles together with links to the three separate sub-pages.

src/codeConventions.md line 41:

> 40:
> 41: ## Motivation{#motivation}
> 42: Code that looks familiar is easier to understand and therefore also easier to review, debug and maintain. To ensure
> that code looks familiar to all developers on the project it?s important to agree on a common set of conventions.

All headers will get anchors automatically, so there's no need to have the {#...} after each header.

src/codeConventions.md line 74:

> 73:
> 74: <div class="box">
> 75: <div class="boxheader">Motivation</div>

You can use markdown to create a div with a specific class, as used for the navigation bars for instance:
::: {.NavBit}
[? Previous](codeConventions.html) ? [TOC](index.html) ? [Next ?](reviewBodies.html)
:::

src/codeConventions.md line 6:

> 5: :::
> 6:
> 7: This is a set of code conventions for for JDK Release Projects in the OpenJDK Community. Other OpenJDK Projects, and
> projects outside of OpenJDK, are welcome to adopt these guidelines as they see fit.

There's a lot of html in this file. I would prefer if as much as possible (all?) could be converted to markdown.

src/guidestyle.css line 10:

> 9: /***************************************/
> 10:
> 11: /* Use a section symbol as list item for style guide items */

The style of most things should be consistent through the guide, and also with the rest of the pages on
openjdk.java.net. I don't mind improving on that style, but that should be a separate change that is applied to all
pages.

src/codeConventions.md line 125:

> 124:
> 125: For questions regarding Oracle copyright or license notices, please contact <a
> href="mailto:iris.clark at oracle.com">iris.clark at oracle.com</a>. 126:

Did Iris agree to this? :-)

src/codeConventions.md line 405:

> 404: <ul class="conventions">
> 405: <li>Source code and comments should generally not exceed 80 characters per line and rarely if ever exceed 100
> characters per line, including indentation. 406: <div class="box">

Was this actually agreed to? 80 cars is a truly ancient number. Especially Java code tends to be slightly chatty and
have longer lines, especially with a few levels of indentation. I wouldn't want to have lines up to 180-200 characters,
but 120-140 is not excessive in my mind.

I'm looking at some Java code I wrote not long ago with an inline Thread - run() declaration inside an if, with a loop
and a few ifs in it... This may be exceptionally bad Java code, but it has four spaces of indentation and 9 indentation
steps in the deepest end. That's almost half of the 80 chars in just indentation. I personally don't find this code the
least difficult to read. But then again, the actual lines themselves are not more than ~100 characters long, they are
just moved to the right a bit due to indentation.  Could the 80-100 lines be excluding indentation?

-------------

Changes requested by jwilhelm (Lead).

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 18 13:10:21 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 18 Jun 2020 13:10:21 GMT
Subject: RFR: Updated section on Code Conventions.
Message-ID: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>

Pull request for adding code conventions.

The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.

[1] http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html
[2] http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html
[3] http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

-------------

Commit messages:
 - Removed all html from style guide.
 - Put Java specific sections in separate file.
 - Updated section on Code Conventions.

Changes: https://git.openjdk.java.net/guide/pull/14/files
 Webrev: https://webrevs.openjdk.java.net/guide/14/webrev.00
  Stats: 1495 lines in 3 files changed: 1493 ins; 0 del; 2 mod
  Patch: https://git.openjdk.java.net/guide/pull/14.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/14/head:pull/14

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 18 13:10:26 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 18 Jun 2020 13:10:26 GMT
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <m69dXE0tCvtbp9Rm0zjvU-gtSrKi-BgbLju24Q9agw0=.f159e3e4-128b-46c2-a189-61a8c722058c@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <m69dXE0tCvtbp9Rm0zjvU-gtSrKi-BgbLju24Q9agw0=.f159e3e4-128b-46c2-a189-61a8c722058c@github.com>
Message-ID: <9iqi5mELVKCLhpSoWPl-1KHAvx11LQTWaqDp4BJcXbM=.03434f44-a7a7-4554-b70e-03846d5c9834@github.com>

On Mon, 1 Jun 2020 00:26:23 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Pull request for adding code conventions.
>> 
>> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
>> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
>> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
>> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html
>
> src/codeConventions.md line 7:
> 
>> 6:
>> 7: This is a set of code conventions for for JDK Release Projects in the OpenJDK Community. Other OpenJDK Projects, and
>> projects outside of OpenJDK, are welcome to adopt these guidelines as they see fit. 8:
> 
> This code convention is for Java code only, right? I'm thinking that we want to have a separate style guide for C++
> code, and there will be one for markdown as well since it's used in several places in the docs. For this reason I think
> it would be better if the actual style guide was on a separate page and this main style-page only has the Motivation
> and Guiding Principles together with links to the three separate sub-pages.

Good point. Updated according to your suggestion.

> src/codeConventions.md line 41:
> 
>> 40:
>> 41: ## Motivation{#motivation}
>> 42: Code that looks familiar is easier to understand and therefore also easier to review, debug and maintain. To ensure
>> that code looks familiar to all developers on the project it?s important to agree on a common set of conventions.
> 
> All headers will get anchors automatically, so there's no need to have the {#...} after each header.

Nice. They have now been removed.

> src/codeConventions.md line 74:
> 
>> 73:
>> 74: <div class="box">
>> 75: <div class="boxheader">Motivation</div>
> 
> You can use markdown to create a div with a specific class, as used for the navigation bars for instance:
> ::: {.NavBit}
> [? Previous](codeConventions.html) ? [TOC](index.html) ? [Next ?](reviewBodies.html)
> :::

Nice. Updated.

> src/codeConventions.md line 6:
> 
>> 5: :::
>> 6:
>> 7: This is a set of code conventions for for JDK Release Projects in the OpenJDK Community. Other OpenJDK Projects, and
>> projects outside of OpenJDK, are welcome to adopt these guidelines as they see fit.
> 
> There's a lot of html in this file. I would prefer if as much as possible (all?) could be converted to markdown.

Managed to remove all HTML thanks to your suggestion on using the `:::` syntax.

> src/guidestyle.css line 10:
> 
>> 9: /***************************************/
>> 10:
>> 11: /* Use a section symbol as list item for style guide items */
> 
> The style of most things should be consistent through the guide, and also with the rest of the pages on
> openjdk.java.net. I don't mind improving on that style, but that should be a separate change that is applied to all
> pages.

I did my best to reduce it to a minimum in the last commit. Also introduced the `.conventions` class to limit the
applicability.

Unfortunately parts of the style guide is barely readable without some styling. (Consecutive code blocks doesn't look
like separate code blocks for example.) Happy to improve further if you have suggestions.

> src/codeConventions.md line 125:
> 
>> 124:
>> 125: For questions regarding Oracle copyright or license notices, please contact <a
>> href="mailto:iris.clark at oracle.com">iris.clark at oracle.com</a>. 126:
> 
> Did Iris agree to this? :-)

Should be removed if Iris objects obviously, but someone suggested adding this when the draft was discussed back in
2015.

> src/codeConventions.md line 405:
> 
>> 404: <ul class="conventions">
>> 405: <li>Source code and comments should generally not exceed 80 characters per line and rarely if ever exceed 100
>> characters per line, including indentation. 406: <div class="box">
> 
> Was this actually agreed to? 80 cars is a truly ancient number. Especially Java code tends to be slightly chatty and
> have longer lines, especially with a few levels of indentation. I wouldn't want to have lines up to 180-200 characters,
> but 120-140 is not excessive in my mind.  I'm looking at some Java code I wrote not long ago with an inline Thread -
> run() declaration inside an if, with a loop and a few ifs in it... This may be exceptionally bad Java code, but it has
> four spaces of indentation and 9 indentation steps in the deepest end. That's almost half of the 80 chars in just
> indentation. I personally don't find this code the least difficult to read. But then again, the actual lines themselves
> are not more than ~100 characters long, they are just moved to the right a bit due to indentation.  Could the 80-100
> lines be excluding indentation?

I think most people agree with you on this (including me). Questions like these however tend to be a bit contentious so
we opted to just let the [existing
conventions](https://www.oracle.com/java/technologies/javase/codeconventions-indentation.html#313) carry over here.
This is probably something that's worth starting a separate discussion about, but I suggest we do that in a separate
change.

Does this sound good to you?

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From iris at openjdk.java.net  Thu Jun 18 17:21:17 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Thu, 18 Jun 2020 17:21:17 GMT
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <9iqi5mELVKCLhpSoWPl-1KHAvx11LQTWaqDp4BJcXbM=.03434f44-a7a7-4554-b70e-03846d5c9834@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <m69dXE0tCvtbp9Rm0zjvU-gtSrKi-BgbLju24Q9agw0=.f159e3e4-128b-46c2-a189-61a8c722058c@github.com>
 <9iqi5mELVKCLhpSoWPl-1KHAvx11LQTWaqDp4BJcXbM=.03434f44-a7a7-4554-b70e-03846d5c9834@github.com>
Message-ID: <DPq_-ASOqTpUnd-ltpiDS2rHRM12bfPTOkVSb5C7Sok=.33e668e3-6268-4a58-9409-ad8e704f91e8@github.com>

On Mon, 15 Jun 2020 14:07:17 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

>> src/codeConventions.md line 125:
>> 
>>> 124:
>>> 125: For questions regarding Oracle copyright or license notices, please contact <a
>>> href="mailto:iris.clark at oracle.com">iris.clark at oracle.com</a>. 126:
>> 
>> Did Iris agree to this? :-)
>
> Should be removed if Iris objects obviously, but someone suggested adding this when the draft was discussed back in
> 2015.

Thanks for asking!  I don't object.

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From jwilhelm at openjdk.java.net  Thu Jun 18 17:46:43 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 18 Jun 2020 17:46:43 GMT
Subject: RFR: New text about mailing lists [v4]
In-Reply-To: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
Message-ID: <8BlPMOqs0cvX5wWvDVHPrBugroXstdUKrOEIQHxOVZ8=.3291d570-6942-42fe-a78a-e31bcd99c72a@github.com>

> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
> lists are used though.

Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:

  Minor fixes after review

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/17/files
  - new: https://git.openjdk.java.net/guide/pull/17/files/2319b7a2..889d4373

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/17/webrev.03
 - incr: https://webrevs.openjdk.java.net/guide/17/webrev.02-03

  Stats: 6 lines in 1 file changed: 4 ins; 0 del; 2 mod
  Patch: https://git.openjdk.java.net/guide/pull/17.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/17/head:pull/17

PR: https://git.openjdk.java.net/guide/pull/17

From jwilhelm at openjdk.java.net  Thu Jun 18 17:46:43 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 18 Jun 2020 17:46:43 GMT
Subject: Integrated: New text about mailing lists
In-Reply-To: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
Message-ID: <UA9xZCRQBLw3JpBpfv0yx8bFQ_mFqWMpYelr280p-ug=.0ac46cc1-d9eb-47d8-aa8d-16cb19dea72f@github.com>

On Wed, 10 Jun 2020 23:30:21 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
> lists are used though.

This pull request has now been integrated.

Changeset: 4a81d9f9
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/guide/commit/4a81d9f9
Stats:     61 lines in 2 files changed: 0 ins; 50 del; 11 mod

New text about mailing lists

Reviewed-by: ihse, iris

-------------

PR: https://git.openjdk.java.net/guide/pull/17

From jesper.wilhelmsson at oracle.com  Thu Jun 18 17:59:45 2020
From: jesper.wilhelmsson at oracle.com (Jesper Wilhelmsson)
Date: Thu, 18 Jun 2020 19:59:45 +0200
Subject: RFR: New text about mailing lists [v3]
In-Reply-To: <99MHvct34yDbxeg8DTNGu3PivUZJoP7b8KPcy6symrU=.50350a1c-aeba-4195-8f43-1ffe1e2a2e2f@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
 <HnqQEWAEcmd9VSUjKR2Pe2JlSy7Jpt0Qbxv_27PvYdE=.90697a6c-56b2-4b64-ba93-bbcdd03482d6@github.com>
 <99MHvct34yDbxeg8DTNGu3PivUZJoP7b8KPcy6symrU=.50350a1c-aeba-4195-8f43-1ffe1e2a2e2f@github.com>
Message-ID: <D935B176-BC57-4715-9E91-4F13539C4715@oracle.com>

> I'm wondering if subscription recommendations should be made for those new to OpenJDK?  Whenever I'm asked, my response
> is usually announce, discuss, and the "-dev" list(s?) covering the explicit area of interest.
> 
> Random note:  Per the Bylaws, OpenJDK mailing list subscribers are defined as "Participants"
> (https://openjdk.java.net/bylaws#participant).

Thanks for the review! I added the recommendation as per your suggestion.

Thanks,
/Jesper


From iris at openjdk.java.net  Thu Jun 18 18:07:18 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Thu, 18 Jun 2020 18:07:18 GMT
Subject: RFR: New text about mailing lists [v4]
In-Reply-To: <8BlPMOqs0cvX5wWvDVHPrBugroXstdUKrOEIQHxOVZ8=.3291d570-6942-42fe-a78a-e31bcd99c72a@github.com>
References: <UORNIMA4u_IxvQEQJVS1Pj4U1Mm0ZJeOwBgCt-jdkG0=.9f1379ff-0947-48ee-bbf0-963bfa56b1ef@github.com>
 <8BlPMOqs0cvX5wWvDVHPrBugroXstdUKrOEIQHxOVZ8=.3291d570-6942-42fe-a78a-e31bcd99c72a@github.com>
Message-ID: <wGslh7wbrCLMdvQdDNYYPHEv9J2q-8WMwUmRFWYoRrk=.b98c4a1c-3f2b-49f8-9619-024c02c0cbc7@github.com>

On Thu, 18 Jun 2020 17:46:43 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> The last three types of lists, used for expert groups, could use a better explanation. I'm not sure how these types of
>> lists are used though.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Minor fixes after review

src/mailingLists.md line 11:

> 10: in the [Bylaws](https://openjdk.java.net/bylaws). As a general recommendation we suggest
> 11: to subscribe to [announce](http://mail.openjdk.java.net/mailman/listinfo/announce),
> 12: [discuss](http://mail.openjdk.java.net/mailman/listinfo/discuss), and the `-dev` lists

Consider using "https" instead of "http" for references to mailing lists.

-------------

PR: https://git.openjdk.java.net/guide/pull/17

From mr at openjdk.java.net  Thu Jun 18 23:17:12 2020
From: mr at openjdk.java.net (Mark Reinhold)
Date: Thu, 18 Jun 2020 23:17:12 GMT
Subject: RFR: Copy edits, terminology fixes,
 and factual corrections to the README and the introduction
Message-ID: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>

- Change ?OpenJDK community? to ?OpenJDK Community?
- Omit needless words
- s/like/such as/g
- Fix various typos and grammatical errors
- Tone down ?contains the defacto standard? to ?suggests?
- The OpenJDK Community was launched in November 2006, not May 2007

-------------

Commit messages:
 - Copy edits, terminology fixes, and factual corrections

Changes: https://git.openjdk.java.net/guide/pull/18/files
 Webrev: https://webrevs.openjdk.java.net/guide/18/webrev.00
  Stats: 37 lines in 2 files changed: 1 ins; 0 del; 36 mod
  Patch: https://git.openjdk.java.net/guide/pull/18.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/18/head:pull/18

PR: https://git.openjdk.java.net/guide/pull/18

From jwilhelm at openjdk.java.net  Fri Jun 19 04:05:00 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Fri, 19 Jun 2020 04:05:00 GMT
Subject: RFR: Copy edits, terminology fixes,
 and factual corrections to the README and the introduction
In-Reply-To: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
References: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
Message-ID: <vxg3nuSAKIgmwpzomEe9Bsfw6E--hf0Sfk1f5HmJbks=.862bf318-d410-48ff-9e31-7c4200908022@github.com>

On Thu, 18 Jun 2020 21:37:45 GMT, Mark Reinhold <mr at openjdk.org> wrote:

> - Change ?OpenJDK community? to ?OpenJDK Community?
> - Omit needless words
> - s/like/such as/g
> - Fix various typos and grammatical errors
> - Tone down ?contains the defacto standard? to ?suggests?
> - The OpenJDK Community was launched in November 2006, not May 2007

Thank you for these changes!  Just a minor typo to fix before pushing.

README.md line 21:

> 20: for experienced contributors. Any descriptions in the Guide should thus be self-contained
> 21: or have explicit references to any information thata the reader is expected to already know. The information
> 22: should also be structured in such a way that it's easy to find the details for any process, so that

"thata" -> "that" ?

-------------

Marked as reviewed by jwilhelm (Lead).

PR: https://git.openjdk.java.net/guide/pull/18

From mr at openjdk.java.net  Fri Jun 19 23:38:31 2020
From: mr at openjdk.java.net (Mark Reinhold)
Date: Fri, 19 Jun 2020 23:38:31 GMT
Subject: RFR: Copy edits, terminology fixes,
 and factual corrections to the README and the introduction
In-Reply-To: <vxg3nuSAKIgmwpzomEe9Bsfw6E--hf0Sfk1f5HmJbks=.862bf318-d410-48ff-9e31-7c4200908022@github.com>
References: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
 <vxg3nuSAKIgmwpzomEe9Bsfw6E--hf0Sfk1f5HmJbks=.862bf318-d410-48ff-9e31-7c4200908022@github.com>
Message-ID: <uoFO62W-9QkvR9cG64RsKIFazOsDt5uL9T4cORmxJTY=.9d3b8ed1-7e8c-42f6-889f-58650e61c1ec@github.com>

On Fri, 19 Jun 2020 04:02:48 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> - Change ?OpenJDK community? to ?OpenJDK Community?
>> - Omit needless words
>> - s/like/such as/g
>> - Fix various typos and grammatical errors
>> - Tone down ?contains the defacto standard? to ?suggests?
>> - The OpenJDK Community was launched in November 2006, not May 2007
>
> Thank you for these changes!  Just a minor typo to fix before pushing.

2020/6/18 21:03:01 -0700, notifications at github.com:
> @JesperIRL approved this pull request.
> 
> Thank you for these changes!  Just a minor typo to fix before pushing.
> 
>> what this guide has to offer. Still, the Developers' Guide should work as a source of knowledge also
> -for experienced contributors. This means that any descriptions in the Guide should be self-contained
> -or have explicit references to any information the reader is expected to already know. The information
> -should also be structured in such a way that it's easy to find details for any process, so that
> -one who already knows the big picture can quickly find that particular detail that was forgotten.
> +for experienced contributors. Any descriptions in the Guide should thus be self-contained
> +or have explicit references to any information thata the reader is expected to already know. The information
> 
> "thata" -> "that" ?

Thanks -- will fix.

- Mark

-------------

PR: https://git.openjdk.java.net/guide/pull/18

From mr at openjdk.java.net  Fri Jun 19 23:52:12 2020
From: mr at openjdk.java.net (Mark Reinhold)
Date: Fri, 19 Jun 2020 23:52:12 GMT
Subject: RFR: Copy edits, terminology fixes,
 and factual corrections to the README and the introduction [v2]
In-Reply-To: <kYejNKQLkAeEGTpvn5hL6w3fhLxTA8MgSND1Rpl6tsg=.3a53bb45-ead1-448c-94b3-aa8a53201a0e@github.com>
References: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
 <vxg3nuSAKIgmwpzomEe9Bsfw6E--hf0Sfk1f5HmJbks=.862bf318-d410-48ff-9e31-7c4200908022@github.com>
 <uoFO62W-9QkvR9cG64RsKIFazOsDt5uL9T4cORmxJTY=.9d3b8ed1-7e8c-42f6-889f-58650e61c1ec@github.com>
 <kYejNKQLkAeEGTpvn5hL6w3fhLxTA8MgSND1Rpl6tsg=.3a53bb45-ead1-448c-94b3-aa8a53201a0e@github.com>
Message-ID: <fU7VAzyIbIhrw3rkYko6vtqOvqYr3vnYxQ5zzpe7PCk=.f7055f58-f68b-49bb-a3ab-429b06d14ef9@github.com>

On Fri, 19 Jun 2020 23:42:16 GMT, Mark Reinhold <mr at openjdk.org> wrote:

>> 2020/6/18 21:03:01 -0700, notifications at github.com:
>>> @JesperIRL approved this pull request.
>>> 
>>> Thank you for these changes!  Just a minor typo to fix before pushing.
>>> 
>>>> what this guide has to offer. Still, the Developers' Guide should work as a source of knowledge also
>>> -for experienced contributors. This means that any descriptions in the Guide should be self-contained
>>> -or have explicit references to any information the reader is expected to already know. The information
>>> -should also be structured in such a way that it's easy to find details for any process, so that
>>> -one who already knows the big picture can quickly find that particular detail that was forgotten.
>>> +for experienced contributors. Any descriptions in the Guide should thus be self-contained
>>> +or have explicit references to any information thata the reader is expected to already know. The information
>>> 
>>> "thata" -> "that" ?
>> 
>> Thanks -- will fix.
>> 
>> - Mark
>
> /summary
>   - Change ?OpenJDK community? to ?OpenJDK Community?
>   - Omit needless words
>   - s/like/such as/g
>   - Fix various typos and grammatical errors
>   - Tone down ?contains the defacto standard? to ?suggests?
>   - The OpenJDK Community was launched in November 2006, not May 2007

/integrate

-------------

PR: https://git.openjdk.java.net/guide/pull/18

From mr at openjdk.java.net  Fri Jun 19 23:52:12 2020
From: mr at openjdk.java.net (Mark Reinhold)
Date: Fri, 19 Jun 2020 23:52:12 GMT
Subject: Integrated: Copy edits, terminology fixes,
 and factual corrections to the README and the introduction
In-Reply-To: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
References: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
Message-ID: <wINx8m5rwrm0v8uKk-4BSOQCR75D3pKk8iYLAXKe-d4=.79973b71-91ba-4d4a-8469-ee6a51f2b105@github.com>

On Thu, 18 Jun 2020 21:37:45 GMT, Mark Reinhold <mr at openjdk.org> wrote:

> - Change ?OpenJDK community? to ?OpenJDK Community?
> - Omit needless words
> - s/like/such as/g
> - Fix various typos and grammatical errors
> - Tone down ?contains the defacto standard? to ?suggests?
> - The OpenJDK Community was launched in November 2006, not May 2007

This pull request has now been integrated.

Changeset: f192a324
Author:    Mark Reinhold <mr at openjdk.org>
URL:       https://git.openjdk.java.net/guide/commit/f192a324
Stats:     37 lines in 2 files changed: 0 ins; 1 del; 36 mod

Copy edits, terminology fixes, and factual corrections to the README and the introduction

Reviewed-by: jwilhelm

-------------

PR: https://git.openjdk.java.net/guide/pull/18

From mr at openjdk.java.net  Fri Jun 19 23:52:05 2020
From: mr at openjdk.java.net (Mark Reinhold)
Date: Fri, 19 Jun 2020 23:52:05 GMT
Subject: RFR: Copy edits, terminology fixes,
 and factual corrections to the README and the introduction [v2]
In-Reply-To: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
References: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
Message-ID: <qS43Q8kS_CZLhD5zQCOkxIGdRvZPOJJDYEJSVZVFUtU=.ffcbfa2b-7ed9-404f-9af0-880112cb01ae@github.com>

> - Change ?OpenJDK community? to ?OpenJDK Community?
> - Omit needless words
> - s/like/such as/g
> - Fix various typos and grammatical errors
> - Tone down ?contains the defacto standard? to ?suggests?
> - The OpenJDK Community was launched in November 2006, not May 2007

Mark Reinhold has updated the pull request incrementally with one additional commit since the last revision:

  Fix typo

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/18/files
  - new: https://git.openjdk.java.net/guide/pull/18/files/0a3f8b25..be87009e

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/18/webrev.01
 - incr: https://webrevs.openjdk.java.net/guide/18/webrev.00-01

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/guide/pull/18.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/18/head:pull/18

PR: https://git.openjdk.java.net/guide/pull/18

From mr at openjdk.java.net  Fri Jun 19 23:52:12 2020
From: mr at openjdk.java.net (Mark Reinhold)
Date: Fri, 19 Jun 2020 23:52:12 GMT
Subject: RFR: Copy edits, terminology fixes,
 and factual corrections to the README and the introduction [v2]
In-Reply-To: <uoFO62W-9QkvR9cG64RsKIFazOsDt5uL9T4cORmxJTY=.9d3b8ed1-7e8c-42f6-889f-58650e61c1ec@github.com>
References: <plZeDW3Iw_gilyqgXVc8X15dC1dkBrCcn3hHUe-cN6k=.c6739536-fe58-4781-943c-a8945ea86fc4@github.com>
 <vxg3nuSAKIgmwpzomEe9Bsfw6E--hf0Sfk1f5HmJbks=.862bf318-d410-48ff-9e31-7c4200908022@github.com>
 <uoFO62W-9QkvR9cG64RsKIFazOsDt5uL9T4cORmxJTY=.9d3b8ed1-7e8c-42f6-889f-58650e61c1ec@github.com>
Message-ID: <kYejNKQLkAeEGTpvn5hL6w3fhLxTA8MgSND1Rpl6tsg=.3a53bb45-ead1-448c-94b3-aa8a53201a0e@github.com>

On Fri, 19 Jun 2020 23:36:26 GMT, Mark Reinhold <mr at openjdk.org> wrote:

>> Thank you for these changes!  Just a minor typo to fix before pushing.
>
> 2020/6/18 21:03:01 -0700, notifications at github.com:
>> @JesperIRL approved this pull request.
>> 
>> Thank you for these changes!  Just a minor typo to fix before pushing.
>> 
>>> what this guide has to offer. Still, the Developers' Guide should work as a source of knowledge also
>> -for experienced contributors. This means that any descriptions in the Guide should be self-contained
>> -or have explicit references to any information the reader is expected to already know. The information
>> -should also be structured in such a way that it's easy to find details for any process, so that
>> -one who already knows the big picture can quickly find that particular detail that was forgotten.
>> +for experienced contributors. Any descriptions in the Guide should thus be self-contained
>> +or have explicit references to any information thata the reader is expected to already know. The information
>> 
>> "thata" -> "that" ?
> 
> Thanks -- will fix.
> 
> - Mark

/summary
  - Change ?OpenJDK community? to ?OpenJDK Community?
  - Omit needless words
  - s/like/such as/g
  - Fix various typos and grammatical errors
  - Tone down ?contains the defacto standard? to ?suggests?
  - The OpenJDK Community was launched in November 2006, not May 2007

-------------

PR: https://git.openjdk.java.net/guide/pull/18

From darcy at openjdk.java.net  Sat Jun 20 03:01:21 2020
From: darcy at openjdk.java.net (Joe Darcy)
Date: Sat, 20 Jun 2020 03:01:21 GMT
Subject: RFR: Update ccc discussion to CSR
Message-ID: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>

Update ccc discussion to CSR

-------------

Commit messages:
 - Update changePlanning.md
 - Update changePlanning.md
 - Update reviewBodies.md

Changes: https://git.openjdk.java.net/guide/pull/19/files
 Webrev: https://webrevs.openjdk.java.net/guide/19/webrev.00
  Stats: 7 lines in 2 files changed: 0 ins; 1 del; 6 mod
  Patch: https://git.openjdk.java.net/guide/pull/19.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/19/head:pull/19

PR: https://git.openjdk.java.net/guide/pull/19

From jwilhelm at openjdk.java.net  Sat Jun 20 16:57:40 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Sat, 20 Jun 2020 16:57:40 GMT
Subject: RFR: Update ccc discussion to CSR
In-Reply-To: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>
References: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>
Message-ID: <bhqcqLC8gqvsAn-AhzLzjk-LM3HeiIH7jfYO6nFcZSQ=.dc4ff72f-1903-4c34-a892-b6c84c18f0e3@github.com>

On Sat, 20 Jun 2020 02:45:59 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Update ccc discussion to CSR

Looks good!  One typo to fix before pushing.

src/changePlanning.md line 80:

> 79:         repository. The work may begin concurrently with the CSR review, but may
> 80:         need to be update in response to CSR review. A summary of the CSR process
> 81:         may be found in [Review Bodies](reviewBodies.html).

"update" -> "updated"

-------------

Marked as reviewed by jwilhelm (Lead).

PR: https://git.openjdk.java.net/guide/pull/19

From darcy at openjdk.java.net  Sat Jun 20 20:19:56 2020
From: darcy at openjdk.java.net (Joe Darcy)
Date: Sat, 20 Jun 2020 20:19:56 GMT
Subject: RFR: Update ccc discussion to CSR [v2]
In-Reply-To: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>
References: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>
Message-ID: <_W0dhdIHtx6nY9Espq9h28YOywD5ewNLAneBILrEABM=.87731b65-ff69-4d12-9b73-b40ac2d800cd@github.com>

> Update ccc discussion to CSR

Joe Darcy has updated the pull request incrementally with two additional commits since the last revision:

 - Update changePlanning.md
 - Update changePlanning.md

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/19/files
  - new: https://git.openjdk.java.net/guide/pull/19/files/cf1c10e5..957d4a09

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/19/webrev.01
 - incr: https://webrevs.openjdk.java.net/guide/19/webrev.00-01

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/guide/pull/19.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/19/head:pull/19

PR: https://git.openjdk.java.net/guide/pull/19

From darcy at openjdk.java.net  Sat Jun 20 20:19:56 2020
From: darcy at openjdk.java.net (Joe Darcy)
Date: Sat, 20 Jun 2020 20:19:56 GMT
Subject: RFR: Update ccc discussion to CSR [v2]
In-Reply-To: <bhqcqLC8gqvsAn-AhzLzjk-LM3HeiIH7jfYO6nFcZSQ=.dc4ff72f-1903-4c34-a892-b6c84c18f0e3@github.com>
References: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>
 <bhqcqLC8gqvsAn-AhzLzjk-LM3HeiIH7jfYO6nFcZSQ=.dc4ff72f-1903-4c34-a892-b6c84c18f0e3@github.com>
Message-ID: <px2FSbTs3lS0lqZIPgRWRZTxWt-xdLkMA8OKKJo8X4o=.88161cc8-4187-4edf-b1d9-7fc67d4538a4@github.com>

On Sat, 20 Jun 2020 16:55:29 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Joe Darcy has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Update changePlanning.md
>>  - Update changePlanning.md
>
> Looks good!  One typo to fix before pushing.

/integrate

> src/changePlanning.md line 80:
> 
>> 79:         repository. The work may begin concurrently with the CSR review, but may
>> 80:         need to be update in response to CSR review. A summary of the CSR process
>> 81:         may be found in [Review Bodies](reviewBodies.html).
> 
> "update" -> "updated"

Thanks for catching that; will push with slight wording adjustment.

-------------

PR: https://git.openjdk.java.net/guide/pull/19

From darcy at openjdk.java.net  Mon Jun 22 08:09:14 2020
From: darcy at openjdk.java.net (Joe Darcy)
Date: Mon, 22 Jun 2020 08:09:14 GMT
Subject: Integrated: Update ccc discussion to CSR
In-Reply-To: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>
References: <YcnxhaVCasnLL_Djh71lc-60PZI_OueGtrGrnWIrIiQ=.3e8e14b8-3c00-4db6-aedb-4106e8d3bfec@github.com>
Message-ID: <nW56wjxCU0tYXjRaJCKnnExqaQAIyM12EaxcS3LUUM4=.8c901900-6d49-4426-95d3-28a94c14602a@github.com>

On Sat, 20 Jun 2020 02:45:59 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Update ccc discussion to CSR

This pull request has now been integrated.

Changeset: 49dd521c
Author:    Joe Darcy <darcy at openjdk.org>
Committer: Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/guide/commit/49dd521c
Stats:     7 lines in 2 files changed: 1 ins; 0 del; 6 mod

Update ccc discussion to CSR

Reviewed-by: jwilhelm

-------------

PR: https://git.openjdk.java.net/guide/pull/19

From mark.reinhold at oracle.com  Mon Jun 22 16:40:20 2020
From: mark.reinhold at oracle.com (mark.reinhold at oracle.com)
Date: Mon, 22 Jun 2020 09:40:20 -0700
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
Message-ID: <20200622094020.797147833@eggemoggin.niobe.net>

2020/6/18 6:10:21 -0700, Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>:
> Pull request for adding code conventions.

Thanks for contributing this material, but I don?t think that the
Developers? Guide is the right place for it.

If we have agreed policies about coding style then we should treat
them as authoritative, normative information.  As such, they?d be
out of place in a Guide that?s meant only to contain tutorials and
suggestions.

- Mark

From jesper.wilhelmsson at oracle.com  Mon Jun 22 17:42:46 2020
From: jesper.wilhelmsson at oracle.com (Jesper Wilhelmsson)
Date: Mon, 22 Jun 2020 19:42:46 +0200
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <20200622094020.797147833@eggemoggin.niobe.net>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
Message-ID: <2DFA84AD-512D-48C1-98FD-D42822208B51@oracle.com>

> On 22 Jun 2020, at 18:40, mark.reinhold at oracle.com wrote:
> 
> 2020/6/18 6:10:21 -0700, Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>:
>> Pull request for adding code conventions.
> 
> Thanks for contributing this material, but I don?t think that the
> Developers? Guide is the right place for it.
> 
> If we have agreed policies about coding style then we should treat
> them as authoritative, normative information.  As such, they?d be
> out of place in a Guide that?s meant only to contain tutorials and
> suggestions.

I guess there are two ways to look at it - either these are coding style guidelines, or they are authoritative coding style rules. My impression was the former, that they were guidelines, and as such I think the Guide is the right place for them. If these are to be treated as authoritative rules however I agree, the Guide is not the place for them. In that case we should make sure these are published in the right place asap and just have the Guide link to them.

What would be the right place to put coding style rules? Can we put it in the "parent drawer" of the Guide, next to the bylaws, census, etc?

Thanks,
/Jesper


From github.com+5994243+aioobe at openjdk.java.net  Mon Jun 22 20:28:00 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Mon, 22 Jun 2020 20:28:00 GMT
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <m69dXE0tCvtbp9Rm0zjvU-gtSrKi-BgbLju24Q9agw0=.f159e3e4-128b-46c2-a189-61a8c722058c@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <m69dXE0tCvtbp9Rm0zjvU-gtSrKi-BgbLju24Q9agw0=.f159e3e4-128b-46c2-a189-61a8c722058c@github.com>
Message-ID: <yYTZu2ve1QMn8G4CYES7OJsrLTmeh5RzqedFSKXuKpQ=.fc20146f-4db9-4f84-9b00-424f8c559ae9@github.com>

On Mon, 1 Jun 2020 01:05:48 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Pull request for adding code conventions.
>> 
>> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
>> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
>> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
>> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html
>
> Thank you for contributing this style guide. This is something that many have been asking about.

> If we have agreed policies about coding style then we should treat them as authoritative, normative information. As
> such, they'd be out of place in a Guide that's meant only to contain tutorials and suggestions.

Sounds like a very narrow definition of a dev guide. This content is usually even referred to as a style _guide_.

In my head, it's very much in line with the section on _Producing a Changeset_. I imagine the target audience is pretty
much the same too.

That being said, where would you suggest publishing style guides?

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From magnus.ihse.bursie at oracle.com  Tue Jun 23 10:05:40 2020
From: magnus.ihse.bursie at oracle.com (Magnus Ihse Bursie)
Date: Tue, 23 Jun 2020 12:05:40 +0200
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <20200622094020.797147833@eggemoggin.niobe.net>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
Message-ID: <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>

On 2020-06-22 18:40, mark.reinhold at oracle.com wrote:
> 2020/6/18 6:10:21 -0700, Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>:
>> Pull request for adding code conventions.
> Thanks for contributing this material, but I don?t think that the
> Developers? Guide is the right place for it.
>
> If we have agreed policies about coding style then we should treat
> them as authoritative, normative information.  As such, they?d be
> out of place in a Guide that?s meant only to contain tutorials and
> suggestions.
Since we have no agreed policies about coding style, this document *is* 
nothing but a tutorial and suggestion! If you follow these guidelines, 
you patch is much more likely to be accepted by the Reviewers, than if 
it violates them.

I for one would love to see an official coding style policy, but that 
has been an on-and-off discussion for years. In the meantime, the 
Developer Guide is definitely the right place to put Andreas' contribution.

/Magnus
>
> - Mark


From jwilhelm at openjdk.java.net  Thu Jun 25 04:14:32 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 25 Jun 2020 04:14:32 GMT
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
Message-ID: <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>

On Sun, 31 May 2020 20:14:44 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

> Pull request for adding code conventions.
> 
> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

src/codeConventions.md line 7:

> 6:
> 7: This is a set of code conventions for for JDK Release Projects in the OpenJDK Community. Other OpenJDK Projects, and
> projects outside of OpenJDK, are welcome to adopt these guidelines as they see fit. 8:

"for for" -> "for"

src/codeConventions.md line 12:

> 11:
> 12: This document provides guidelines for low level coding practices such as how to indent code and how to name types
> and variables. Many of the stylistic choices are subjective and different developers may have different opinions about
> them. Keep in mind however, that having a consistent style is more important than to satisfy each individual developers
> preference. 13:

"This document" -> "This section"

src/codeConventions.md line 15:

> 14: ## Guiding Principles
> 15: The guidelines in this document strive to maximize,
> 16:

"this document" -> "this section"

src/codeConventions.md line 17:

> 16:
> 17: <ol class="spread">
> 18:     <li>Correctness</li>

Not sure if I'm looking at the latest commit here, but if I do this part should be converted to markdown as well.

src/javaStyleGuide.md line 7:

> 6:
> 7: While this document covers a lot of ground, it should be noted that no style guide can answer all questions for us,
> and developers will always need to use good judgment towards the end of producing code that is correct, readable,
> maintainable, debuggable, consistently formatted, and aesthetically pleasing. 8:

"this document" -> "this section"

src/javaStyleGuide.md line 9:

> 8:
> 9: Examples in this document are non-normative; While they intend to illustrate correct way of formatting the code,
> there may be other ways to correctly format the code. This is a general principle: There may be several ways to format
> the code, all adhering to the guidelines in this document. 10:

"this document" -> "this section" x2
"illustrate correct way" -> "illustrate the correct way" or "illustrate a correct way"

src/javaStyleGuide.md line 46:

> 45: ## Java Source Files
> 46: This section concerns ordinary `.java` files only. Rules do not necessarily apply to other source files such as
> `.jasm`, `.sh` or `.gmk`. 47:

I think these two sentences can be removed since this document now is (intended to be) part of a collection of style
guides for different languages. For instance makefiles is planned to get their own section. The section header is
enough to convey this information.

src/javaStyleGuide.md line 6:

> 5: :::
> 6:
> 7: While this document covers a lot of ground, it should be noted that no style guide can answer all questions for us,
> and developers will always need to use good judgment towards the end of producing code that is correct, readable,
> maintainable, debuggable, consistently formatted, and aesthetically pleasing.

Looking at the division I think that the following text, down to the "Overview", would be better placed in the general
style guide section that is in the other file now. The text is true for the other languages/style guides as well imho.

src/javaStyleGuide.md line 83:

> 82: - A Java source file should be structured as follows:
> 83:   1. The copyright notice
> 84:   1. Package declaration

I would prefer if we stick to #. for numbered lists. This goes throughout the file.

src/javaStyleGuide.md line 1378:

> 1377: Cleaning up code that?s unrelated to the patch may?
> 1378: - Complicate the review of the patch in which case correctness may suffer
> 1379: - Run the risk of breaking existing code

An empty line is needed between text and list.

src/javaStyleGuide.md line 96:

> 95:
> 96:   ```java
> 97:   /*

An indented backtick code block cause problems for syntax highlighting both in my editor and here in the GitHub review.
Actually it's the indentation of the end backticks that cause the problem so this could be fixed by indenting the end
``` with at most one space. However I don't think that looks very good so I suggest to use ~~~ for indented code
blocks. ``` and ~~~ renders the same result with Pandoc. This goes throughout the file.

src/javaStyleGuide.md line 101:

> 100:   or
> 101:   ```java
> 102:   /*

The Pandoc documentation says that fenced code blocks must be separated from surrounding text by blank lines. With ```
it seems to work either way, but ~~~ requires an empty line before the block. In either case the visual result in the
end is the same so I see no reason not to follow the documentation and have empty lines before and after.

src/guidestyle.css line 49:

> 48: /* Code blocks */
> 49: pre > code {
> 50:     border: 1px solid #CCCCCC;

Note that this affects code blocks in the rest of the Guide as well. This is not necessarily a bad thing, but it should
be noted.

src/javaStyleGuide.md line 1075:

> 1074: ### Javadoc
> 1075: This section only covers basic Javadoc formatting. For a complete reference refer to &nbsp;[How to Write Doc
> Comments for the Javadoc Tool](http://www.oracle.com/technetwork/articles/java/index-137868.html). 1076:

Since Javadoc is slightly out of scope, and there is a complete reference for it, can we move it down to where comments
are handled and give it a less prominent placement there?

src/javaStyleGuide.md line 1366:

> 1365: - IDE/tool-specific comments should be avoided wherever possible, especially when there are reasonable
> alternatives, such as external settings files, etc. 1366: - Comments should be grammatically correct and follow general
> recommendations of technical writing. 1367: :::

The three Javadoc lines can be added at the end here and the examples below. Then have the link to the complete guide
in a "For more information..."-link.

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 07:47:41 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 07:47:41 GMT
Subject: RFR: Updated section on Code Conventions. [v2]
In-Reply-To: <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>
Message-ID: <IKPYtVcrRWm0Mukw6AuGosHtbaJMlGkpjoExQU9I_fs=.12271123-3800-46dc-a9ad-2d6bbf87656d@github.com>

On Wed, 24 Jun 2020 22:11:23 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Andreas Lundblad has updated the pull request incrementally with three additional commits since the last revision:
>> 
>>  - Moved Javadoc guidelines to comments section.
>>  - Joined code blocks into a single one in hgHelp and tClone.
>>  - Changed from ``` to ~~~, and from 'document' to 'section'
>
> src/codeConventions.md line 17:
> 
>> 16:
>> 17: <ol class="spread">
>> 18:     <li>Correctness</li>
> 
> Not sure if I'm looking at the latest commit here, but if I do this part should be converted to markdown as well.

Ops. Had forgotten this file. Done.

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 07:47:32 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 07:47:32 GMT
Subject: RFR: Updated section on Code Conventions. [v2]
In-Reply-To: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
Message-ID: <HYSCiaJ41HWSbBlmmcPq36Gmree3CgXseIOjJNXScPQ=.14e16041-837e-40c6-bc44-dada2a7e09ca@github.com>

> Pull request for adding code conventions.
> 
> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

Andreas Lundblad has updated the pull request incrementally with three additional commits since the last revision:

 - Moved Javadoc guidelines to comments section.
 - Joined code blocks into a single one in hgHelp and tClone.
 - Changed from ``` to ~~~, and from 'document' to 'section'

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/14/files
  - new: https://git.openjdk.java.net/guide/pull/14/files/2ca5accd..65db3f10

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/14/webrev.01
 - incr: https://webrevs.openjdk.java.net/guide/14/webrev.00-01

  Stats: 480 lines in 4 files changed: 195 ins; 49 del; 236 mod
  Patch: https://git.openjdk.java.net/guide/pull/14.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/14/head:pull/14

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 08:25:19 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 08:25:19 GMT
Subject: RFR: Updated section on Code Conventions. [v3]
In-Reply-To: <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>
Message-ID: <ofPkx7FJhM-MtZRYag3YqiQnJi--CeqNe8kyuFK2r30=.d469b7bf-9348-4955-8da6-02bd11f5898f@github.com>

On Thu, 25 Jun 2020 03:57:11 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Andreas Lundblad has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Moved introductory text to code conventions page.
>
> src/javaStyleGuide.md line 1075:
> 
>> 1074: ### Javadoc
>> 1075: This section only covers basic Javadoc formatting. For a complete reference refer to &nbsp;[How to Write Doc
>> Comments for the Javadoc Tool](http://www.oracle.com/technetwork/articles/java/index-137868.html). 1076:
> 
> Since Javadoc is slightly out of scope, and there is a complete reference for it, can we move it down to where comments
> are handled and give it a less prominent placement there?

Good suggestion. Updated.

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 08:25:18 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 08:25:18 GMT
Subject: RFR: Updated section on Code Conventions. [v3]
In-Reply-To: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
Message-ID: <3r-UNLak6s-mKIAF_Tqg-mllwZ486v1ZLfMGHWxQefg=.4d8f700c-612e-4b51-a1db-0f51bc9bcda2@github.com>

> Pull request for adding code conventions.
> 
> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

Andreas Lundblad has updated the pull request incrementally with one additional commit since the last revision:

  Moved introductory text to code conventions page.

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/14/files
  - new: https://git.openjdk.java.net/guide/pull/14/files/65db3f10..119ea0cf

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/14/webrev.02
 - incr: https://webrevs.openjdk.java.net/guide/14/webrev.01-02

  Stats: 14 lines in 2 files changed: 6 ins; 8 del; 0 mod
  Patch: https://git.openjdk.java.net/guide/pull/14.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/14/head:pull/14

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 08:36:12 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 08:36:12 GMT
Subject: RFR: Updated section on Code Conventions. [v4]
In-Reply-To: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
Message-ID: <QYS-PfvEyDDP5GSw__Q3UwFvvU5euxD-P8AB1bfEU2c=.816572a6-7534-4ae4-bb91-bf36eacda11f@github.com>

> Pull request for adding code conventions.
> 
> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

Andreas Lundblad has updated the pull request incrementally with two additional commits since the last revision:

 - Changed from 1. to #. in a few ordered lists.
 - Added an empty line to separate text from list.

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/14/files
  - new: https://git.openjdk.java.net/guide/pull/14/files/119ea0cf..d85c4742

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/14/webrev.03
 - incr: https://webrevs.openjdk.java.net/guide/14/webrev.02-03

  Stats: 19 lines in 1 file changed: 1 ins; 0 del; 18 mod
  Patch: https://git.openjdk.java.net/guide/pull/14.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/14/head:pull/14

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 08:36:12 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 08:36:12 GMT
Subject: RFR: Updated section on Code Conventions. [v4]
In-Reply-To: <yYTZu2ve1QMn8G4CYES7OJsrLTmeh5RzqedFSKXuKpQ=.fc20146f-4db9-4f84-9b00-424f8c559ae9@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <m69dXE0tCvtbp9Rm0zjvU-gtSrKi-BgbLju24Q9agw0=.f159e3e4-128b-46c2-a189-61a8c722058c@github.com>
 <yYTZu2ve1QMn8G4CYES7OJsrLTmeh5RzqedFSKXuKpQ=.fc20146f-4db9-4f84-9b00-424f8c559ae9@github.com>
Message-ID: <q_59ja8LrA23u5332LdmT2YnaiVpU84--8Ae2zvgVcw=.30ff4cad-abc6-48ec-95d1-c5b53d5c6970@github.com>

On Mon, 22 Jun 2020 20:25:50 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

>> Thank you for contributing this style guide. This is something that many have been asking about.
>
>> If we have agreed policies about coding style then we should treat them as authoritative, normative information. As
>> such, they'd be out of place in a Guide that's meant only to contain tutorials and suggestions.
> 
> Sounds like a very narrow definition of a dev guide. This content is usually even referred to as a style _guide_.
> 
> In my head, it's very much in line with the section on _Producing a Changeset_. I imagine the target audience is pretty
> much the same too.
> That being said, where would you suggest publishing style guides?

Thanks @JesperIRL, good comments. They should all be addressed now.

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 08:36:15 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 08:36:15 GMT
Subject: RFR: Updated section on Code Conventions. [v4]
In-Reply-To: <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>
Message-ID: <K8fs0w1F4zPFWwU-qlL5ulCOgSopoRsyiREgH8qSau4=.3a3b9f12-1836-4262-b359-8ebd365d00cb@github.com>

On Thu, 25 Jun 2020 03:42:50 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Andreas Lundblad has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Changed from 1. to #. in a few ordered lists.
>>  - Added an empty line to separate text from list.
>
> src/guidestyle.css line 49:
> 
>> 48: /* Code blocks */
>> 49: pre > code {
>> 50:     border: 1px solid #CCCCCC;
> 
> Note that this affects code blocks in the rest of the Guide as well. This is not necessarily a bad thing, but it should
> be noted.

Good point. I grep'ed for `<code` and found out that this styling messed up code blocks in hgHelp and tClone. Updated
those files.

I also noted that code blocks are formatted using blockquotes here and there. Perhaps this is because there hasn't been
any proper styling for code blocks before? I think they should be turned into `~~~`, but I'll address that in a
separate change.

> src/javaStyleGuide.md line 1366:
> 
>> 1365: - IDE/tool-specific comments should be avoided wherever possible, especially when there are reasonable
>> alternatives, such as external settings files, etc. 1366: - Comments should be grammatically correct and follow general
>> recommendations of technical writing. 1367: :::
> 
> The three Javadoc lines can be added at the end here and the examples below. Then have the link to the complete guide
> in a "For more information..."-link.

Not 100% sure I understood. Let me know what you think about the latest version.

> src/javaStyleGuide.md line 96:
> 
>> 95:
>> 96:   ```java
>> 97:   /*
> 
> An indented backtick code block cause problems for syntax highlighting both in my editor and here in the GitHub review.
> Actually it's the indentation of the end backticks that cause the problem so this could be fixed by indenting the end
> ``` with at most one space. However I don't think that looks very good so I suggest to use ~~~ for indented code
> blocks. ``` and ~~~ renders the same result with Pandoc. This goes throughout the file.

Sounds good. Updated.

> src/javaStyleGuide.md line 101:
> 
>> 100:   or
>> 101:   ```java
>> 102:   /*
> 
> The Pandoc documentation says that fenced code blocks must be separated from surrounding text by blank lines. With ```
> it seems to work either way, but ~~~ requires an empty line before the block. In either case the visual result in the
> end is the same so I see no reason not to follow the documentation and have empty lines before and after.

Updated.

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From ihse at openjdk.java.net  Thu Jun 25 09:20:50 2020
From: ihse at openjdk.java.net (Magnus Ihse Bursie)
Date: Thu, 25 Jun 2020 09:20:50 GMT
Subject: RFR: Updated section on Code Conventions. [v4]
In-Reply-To: <QYS-PfvEyDDP5GSw__Q3UwFvvU5euxD-P8AB1bfEU2c=.816572a6-7534-4ae4-bb91-bf36eacda11f@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <QYS-PfvEyDDP5GSw__Q3UwFvvU5euxD-P8AB1bfEU2c=.816572a6-7534-4ae4-bb91-bf36eacda11f@github.com>
Message-ID: <YhdblWwmmcqKwXHoYrMfsF6ivk0wzRub4vWMHuxKsDk=.44c5dc8c-1d63-425f-ad18-1e4a7cf86236@github.com>

On Thu, 25 Jun 2020 08:36:12 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

>> Pull request for adding code conventions.
>> 
>> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
>> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
>> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
>> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html
>
> Andreas Lundblad has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Changed from 1. to #. in a few ordered lists.
>  - Added an empty line to separate text from list.

Looks good to me, both content-wise and formatting-wise.

-------------

Marked as reviewed by ihse (no project role).

PR: https://git.openjdk.java.net/guide/pull/14

From jwilhelm at openjdk.java.net  Thu Jun 25 15:28:56 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 25 Jun 2020 15:28:56 GMT
Subject: RFR: Updated section on Code Conventions. [v4]
In-Reply-To: <K8fs0w1F4zPFWwU-qlL5ulCOgSopoRsyiREgH8qSau4=.3a3b9f12-1836-4262-b359-8ebd365d00cb@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <KRlv_rOl0kWEGeiy2iamQ8S5vUwxf8YsxURqqg_vQiU=.23215488-3d8e-4f55-8e88-93b68f6c25a5@github.com>
 <K8fs0w1F4zPFWwU-qlL5ulCOgSopoRsyiREgH8qSau4=.3a3b9f12-1836-4262-b359-8ebd365d00cb@github.com>
Message-ID: <D_Bfle37O8OQ8SESNQi4RudqwpMR4-9ySmqTsNDIZAU=.18f17b41-e2cd-4048-9b75-c203872d1d5a@github.com>

On Thu, 25 Jun 2020 08:13:46 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

>> src/javaStyleGuide.md line 1366:
>> 
>>> 1365: - IDE/tool-specific comments should be avoided wherever possible, especially when there are reasonable
>>> alternatives, such as external settings files, etc. 1366: - Comments should be grammatically correct and follow general
>>> recommendations of technical writing. 1367: :::
>> 
>> The three Javadoc lines can be added at the end here and the examples below. Then have the link to the complete guide
>> in a "For more information..."-link.
>
> Not 100% sure I understood. Let me know what you think about the latest version.

This is exactly what I wanted ??

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From jwilhelm at openjdk.java.net  Thu Jun 25 15:28:56 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 25 Jun 2020 15:28:56 GMT
Subject: RFR: Updated section on Code Conventions. [v4]
In-Reply-To: <QYS-PfvEyDDP5GSw__Q3UwFvvU5euxD-P8AB1bfEU2c=.816572a6-7534-4ae4-bb91-bf36eacda11f@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <QYS-PfvEyDDP5GSw__Q3UwFvvU5euxD-P8AB1bfEU2c=.816572a6-7534-4ae4-bb91-bf36eacda11f@github.com>
Message-ID: <CviuVzCgwXt8P-FHI1YgcpHHU-K55aHkYeLBLE4QbPo=.815b0edb-a348-4039-a4c9-a661270a5a40@github.com>

On Thu, 25 Jun 2020 08:36:12 GMT, Andreas Lundblad <github.com+5994243+aioobe at openjdk.org> wrote:

>> Pull request for adding code conventions.
>> 
>> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
>> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
>> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
>> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
>> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html
>
> Andreas Lundblad has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Changed from 1. to #. in a few ordered lists.
>  - Added an empty line to separate text from list.

Getting close now ??
But I would like to hear back from Mark on our questions in this thread before approving.

src/javaStyleGuide.md line 4:

> 3: ::: {.NavBit}
> 4: [? Previous](mailinglists.html) ? [TOC](index.html) ??? [Next ?](changePlanning.html)
> 5: :::

I think previous should go to codeConventions.html. Same at the bottom of this file.

src/hgHelp.md line 6:

> 5: :::
> 6:
> 7: >     $ hg help

Good catch!  Thanks for cleaning this up as well!

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 18:31:29 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 18:31:29 GMT
Subject: RFR: Updated section on Code Conventions. [v5]
In-Reply-To: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
Message-ID: <p-vG2GHmTi4GOzkKiszj8gR8g0AcDSgVtZPZh81OHDE=.29053f68-af6f-41aa-bd08-e4f57dcbecc5@github.com>

> Pull request for adding code conventions.
> 
> The code conventions in this pull request is a verbatim copy of [3]. These conventions were the ones discussed in
> detail on discuss at openjdk.java.net in 2015. Two rounds of reviews were performed, [1] [2], and all comments were
> addressed. The 6th and last draft [3] has been stable since then, and been in use by several OpenJDK projects.  [1]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003766.html [2]
> http://mail.openjdk.java.net/pipermail/discuss/2015-August/003771.html [3]
> http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html

Andreas Lundblad has updated the pull request incrementally with one additional commit since the last revision:

  Previous link now points to codeConventions.

-------------

Changes:
  - all: https://git.openjdk.java.net/guide/pull/14/files
  - new: https://git.openjdk.java.net/guide/pull/14/files/d85c4742..a4743642

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/14/webrev.04
 - incr: https://webrevs.openjdk.java.net/guide/14/webrev.03-04

  Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.java.net/guide/pull/14.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/14/head:pull/14

PR: https://git.openjdk.java.net/guide/pull/14

From github.com+5994243+aioobe at openjdk.java.net  Thu Jun 25 18:31:30 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Thu, 25 Jun 2020 18:31:30 GMT
Subject: RFR: Updated section on Code Conventions. [v4]
In-Reply-To: <CviuVzCgwXt8P-FHI1YgcpHHU-K55aHkYeLBLE4QbPo=.815b0edb-a348-4039-a4c9-a661270a5a40@github.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <QYS-PfvEyDDP5GSw__Q3UwFvvU5euxD-P8AB1bfEU2c=.816572a6-7534-4ae4-bb91-bf36eacda11f@github.com>
 <CviuVzCgwXt8P-FHI1YgcpHHU-K55aHkYeLBLE4QbPo=.815b0edb-a348-4039-a4c9-a661270a5a40@github.com>
Message-ID: <FrP0k9ZshDpqFV3dHutHiq8TTVSdtyq8ksubZQe3dHY=.99ed35e2-6209-42fd-a29c-5f2f60a77ad7@github.com>

On Thu, 25 Jun 2020 15:18:49 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Andreas Lundblad has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Changed from 1. to #. in a few ordered lists.
>>  - Added an empty line to separate text from list.
>
> src/javaStyleGuide.md line 4:
> 
>> 3: ::: {.NavBit}
>> 4: [? Previous](mailinglists.html) ? [TOC](index.html) ??? [Next ?](changePlanning.html)
>> 5: :::
> 
> I think previous should go to codeConventions.html. Same at the bottom of this file.

Updated.

-------------

PR: https://git.openjdk.java.net/guide/pull/14

From jwilhelm at openjdk.java.net  Thu Jun 25 18:56:59 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 25 Jun 2020 18:56:59 GMT
Subject: RFR: Makefile
Message-ID: <tq1ylyZyOp7U__7J1SoGyfwX9K2Q6IyUY5g1SaGBsRU=.0f345867-f3bc-4db2-8a61-c12a27b5bccf@github.com>

The build breaks if there are .md files not tracked by git because `git log` returns no hash.

-------------

Commit messages:
 - Fixed linebreak
 - Handle new files

Changes: https://git.openjdk.java.net/guide/pull/20/files
 Webrev: https://webrevs.openjdk.java.net/guide/20/webrev.00
  Stats: 5 lines in 1 file changed: 4 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/guide/pull/20.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/20/head:pull/20

PR: https://git.openjdk.java.net/guide/pull/20

From iris at openjdk.java.net  Thu Jun 25 23:49:10 2020
From: iris at openjdk.java.net (Iris Clark)
Date: Thu, 25 Jun 2020 23:49:10 GMT
Subject: RFR: Makefile
In-Reply-To: <tq1ylyZyOp7U__7J1SoGyfwX9K2Q6IyUY5g1SaGBsRU=.0f345867-f3bc-4db2-8a61-c12a27b5bccf@github.com>
References: <tq1ylyZyOp7U__7J1SoGyfwX9K2Q6IyUY5g1SaGBsRU=.0f345867-f3bc-4db2-8a61-c12a27b5bccf@github.com>
Message-ID: <_clXYQBpjxb8KjXEs2xdo2CE9sWCUy4OaKciTIxXDOA=.80c6c93c-7980-4109-b213-7e8032e4b059@github.com>

On Thu, 25 Jun 2020 18:46:23 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> The build breaks if there are .md files not tracked by git because `git log` returns no hash.

Marked as reviewed by iris (Reviewer).

-------------

PR: https://git.openjdk.java.net/guide/pull/20

From mark.reinhold at oracle.com  Thu Jun 25 23:51:30 2020
From: mark.reinhold at oracle.com (mark.reinhold at oracle.com)
Date: Thu, 25 Jun 2020 16:51:30 -0700
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <2DFA84AD-512D-48C1-98FD-D42822208B51@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <2DFA84AD-512D-48C1-98FD-D42822208B51@oracle.com>
Message-ID: <20200625165130.120841172@eggemoggin.niobe.net>

2020/6/22 10:42:46 -0700, jesper.wilhelmsson at oracle.com:
>> On 22 Jun 2020, at 18:40, mark.reinhold at oracle.com wrote:
>> 
>> 2020/6/18 6:10:21 -0700, Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>:
>>> Pull request for adding code conventions.
>> 
>> Thanks for contributing this material, but I don?t think that the
>> Developers? Guide is the right place for it.
>> 
>> If we have agreed policies about coding style then we should treat
>> them as authoritative, normative information.  As such, they?d be
>> out of place in a Guide that?s meant only to contain tutorials and
>> suggestions.
> 
> I guess there are two ways to look at it - either these are coding
> style guidelines, or they are authoritative coding style rules. My
> impression was the former, that they were guidelines, and as such I
> think the Guide is the right place for them. If these are to be
> treated as authoritative rules however I agree, the Guide is not the
> place for them. In that case we should make sure these are published
> in the right place asap and just have the Guide link to them.

For better or for worse, code style is often a topic of much -- and
sometimes heated -- debate.  No matter what we say about these documents
merely being suggestive guidelines, at least some people will treat them
as normative and authoritative, and use them as the basis for arguing
one way or another.

The Developers? Guide is meant to be a living document, written by its
contributors to help others more easily contribute to the JDK.  As such
it can change at any time.  Changes to it are, moreover, not broadly
reviewed, so it does not necessarily represent a consensus of JDK
contributors.

An authoritative document, by contrast, should be fairly stable, and
changes to it should be subject to broad review so that it represents a
rough consensus of JDK contributors rather than that of a smaller group
of Guide contributors.

A Java style guide published in the OpenJDK Community will also be used
by people in the broader ecosystem who will never contribute to the JDK,
but who?ve been asking us for years for an updated style guide for use
in their own work.  We should therefore try to take extra care with it.

So, I don?t think code style guidelines belong in the Developer?s Guide,
even if they are just ?guidelines.?

> What would be the right place to put coding style rules?

Good question!

Fortunately we already have an established means of building consensus
around authoritative documents, namely the JEP process.  I suggest that
code style guides be published as informational JEPs, alongside existing
prominent JEPs such as those for the release process, incubator modules,
and so forth.

The JEP process and the infrastructure it rests on (JBS) aren?t perfect.
Maintaining long documents in JBS issues, in particular, is painful, and
the JBS Markdown renderer is bonkers.  With a little hacking, however, I
think we can arrange for better revision control and rendering of select
JEPs.

- Mark

From jwilhelm at openjdk.java.net  Fri Jun 26 03:25:43 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Fri, 26 Jun 2020 03:25:43 GMT
Subject: Integrated: Makefile
In-Reply-To: <tq1ylyZyOp7U__7J1SoGyfwX9K2Q6IyUY5g1SaGBsRU=.0f345867-f3bc-4db2-8a61-c12a27b5bccf@github.com>
References: <tq1ylyZyOp7U__7J1SoGyfwX9K2Q6IyUY5g1SaGBsRU=.0f345867-f3bc-4db2-8a61-c12a27b5bccf@github.com>
Message-ID: <OqkM94lQZ-3vQaVFGpaqfjQC5pZvVM-IM4YR3VSn06k=.358439a9-60f9-4086-83ce-0c3622888d5f@github.com>

On Thu, 25 Jun 2020 18:46:23 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

> The build breaks if there are .md files not tracked by git because `git log` returns no hash.

This pull request has now been integrated.

Changeset: 250fc39b
Author:    Jesper Wilhelmsson <jwilhelm at openjdk.org>
URL:       https://git.openjdk.java.net/guide/commit/250fc39b
Stats:     5 lines in 1 file changed: 0 ins; 4 del; 1 mod

Makefile

Reviewed-by: iris

-------------

PR: https://git.openjdk.java.net/guide/pull/20

From magnus.ihse.bursie at oracle.com  Fri Jun 26 14:13:41 2020
From: magnus.ihse.bursie at oracle.com (Magnus Ihse Bursie)
Date: Fri, 26 Jun 2020 16:13:41 +0200
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
Message-ID: <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>

Mark, Andreas, Jesper,

First of all, I think this question is of far too much importance to 
discuss only for the reviewers on guide-dev, so I'm widening the scope 
to include jdk-dev. I am certainly not alone in thinking that having the 
Style Guidelines was a major part of what the Developer's Guide Project 
was all about.

Secondly, for some reason, I have not gotten any further emails from 
this code review. :-( Possibly it's related to the many hiccups of the 
ojn mailing list server lately. I have tried quoting part of Mark's 
comment here by copying it from GitHub. I apologize if the formatting is 
a bit odd due to this.
> No matter what we say about these documents merely being suggestive 
> guidelines, at least some people will treat them as normative and 
> authoritative, and use them as the basis for arguing one way or another.
I do not agree that this is a valid argument. We can't claim that we 
should not publish guidelines, since some people will not understand 
what "guidelines" mean. If you are serious about this argument, then we 
can just as well shut down the entire Developer's Guide, since it's all 
about non-authoritative suggestions.

The fact that "some people can misunderstand" is hardly ever a good 
reason not to provide information that is highly useful to the vast 
majority who do not misunderstand.
> A Java style guide published in the OpenJDK Community will also be 
> used by people in the broader ecosystem who will never contribute to 
> the JDK, but who?ve been asking us for years for an updated style 
> guide for use in their own work. We should therefore try to take extra 
> care with it.
Oh, really? We missed that train years ago. If we had published updated 
style guides when everybody was screaming for it, we could have had an 
impact on the wider Java community. But we did not, and our official 
style rules slid into oblivion.

That crown position has been taking mostly by Google's Java Style Guide [1].

We might be able to restore our position as a beacon to the rest of the 
Java community, or we might not. I'm not even sure if it is a good thing 
for the OpenJDK community as such if our internal processes are governed 
in fear of making a mess for a group of unknown outsiders.

And even if we do think it is desirable, for every year we wait until we 
publish a guide, the harder it will become to create a new, globally 
recognized, normative style guide.
> So, I don?t think code style guidelines belong in the Developer?s 
> Guide, even if they are just ?guidelines.
> [...]
> An authoritative document, by contrast, should be fairly stable, and 
> changes to it should be subject to broad review so that it represents 
> a rough consensus of JDK contributors rather than that of a smaller 
> group of Guide contributors.
> [...]
> Fortunately we already have an established means of building consensus 
> around authoritative documents, namely the JEP process. I suggest that 
> code style guides be published as informational JEPs, alongside 
> existing prominent JEPs such as those for the release process, 
> incubator modules, and so forth.
First of all, I wholeheartedly object to the view presented here that 
the JEP process is an inclusive and democratic way of bringing the 
OpenJDK community forward.

On the contrast, JEPs tend to mostly be authoritative documents written 
by the authors and endorsers, and feedback from the community is 
all-too-often ignored. There is no way an outsider can submit a patch to 
a JEP and have it reviewed, discussed, and/or accepted. Instead, anyone 
objecting to a JEP will need to communicate their sentiment on the 
mailing list, and watching the authors of the JEP get inspired by it, or 
ignore it, all at their own will. There is no voting about JEPs. 
Non-informational JEPs give the wider community a choice to come with 
"reasonable objects", but that is only a binary choice on a completed 
proposal, and it does not even apply to Informational JEPs that are 
supposed to be continuously updated.

I do not want to go into a discussion if this is a method that works 
well for planned features in the JDK (let's assume so for now, and save 
that question for a rainy day!). But it is certainly not a process that 
is any more inclusive than having the Style Guide as a project on 
Github. On the contrast, here any OpenJDK Member is free to publish a 
patch, and have it discussed, in the open, by all other members. If 
anything, the error in this process lies in the unfortunate fact that 
not all OpenJDK Members were made initial Reviewers of the Guide Project.

Finally, I want to bring notice to the fact that Andreas' proposal for a 
Style Guide was ready, with basically the same contents that are being 
proposed here, in 2015. That is 5 years ago! For all this time we have 
been without any written document to guide us, formal or informal. If 
you believe a JEP had been the best way forward in this issue, as the 
JDK Team Lead you have had ample of time to get that ball rolling.

If you want to create an Informational JEP, with an authoritative style 
guide, fine, go ahead. But, in the meantime, do not block the 
Developer's Guide from having a written document to help and support the 
actual developers that struggle everyday with trying to write good, 
readable code, or for that matter, reviewers who are in need of guidance 
of what to accept or reject, or who have to repeat, over and over again, 
to newcomers how code is supposed to look to be accepted.

The lack of this document does not mean that "anything goes". It just 
makes the knowledge invisibly buried in the heads of a few developers 
and reviewers, were it cannot be easily shared, and where it steals 
precious time from said developers in repeating these rules over and 
over in reviews.

My suggestion to resolving these conflicting views on what the code 
style guideline should be, by adding a large header to the document with 
something like: "This is a non-authoritative document, and is considered 
an interim solution. An Informational JEP with the purpose of being a 
formal, authoritative document for the Style Guide is being worked upon, 
and will fully replace this document when it is completed."

/Magnus

[1] https://google.github.io/styleguide/javaguide.html


From jesper.wilhelmsson at oracle.com  Fri Jun 26 15:41:55 2020
From: jesper.wilhelmsson at oracle.com (Jesper Wilhelmsson)
Date: Fri, 26 Jun 2020 17:41:55 +0200
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
Message-ID: <A2CF77F1-08D0-46E4-BD8B-428F09A9448A@oracle.com>

I'll only quote a part of Magnus' mail here because to me there really is only one question: Is the style guide an authoritative set of rules or is it a guide with suggestions?

>> No matter what we say about these documents merely being suggestive guidelines, at least some people will treat them as normative and authoritative, and use them as the basis for arguing one way or another.
> I do not agree that this is a valid argument. We can't claim that we should not publish guidelines, since some people will not understand what "guidelines" mean. If you are serious about this argument, then we can just as well shut down the entire Developer's Guide, since it's all about non-authoritative suggestions.
> 
> The fact that "some people can misunderstand" is hardly ever a good reason not to provide information that is highly useful to the vast majority who do not misunderstand.

I agree with Magnus here, we can't treat it as a set of rules if it isn't a set of rules. I'm totally fine with placing it in a JEP if these are rules, but that also means that everyone are expected to follow these rules, and I'm sure that will result in a lot more policing than we see today.

If the style guide is what it's called, a guide, then having it in a JEP will actually cause more damage since it will not only be a few people who mistakenly treat it as a set of rules, it will actually look like a set of rules for the vast majority of the readers. The Developers' Guide will even (at least with the current wording) say that it is a set of rules, "The formal rules and processes are described in other documents, like JEP 1 ..., or JEP 3...".

The current wording of the style guide clearly states that it's a guide with suggestions in several places throughout the text and at least everyone I have spoken to about style guides have agreed that these should not dictate a fix set of rules that may never be broken but should rather be guidelines with flexibility when needed. If this is a JEP that is flexible, how will that affect other JEPs? Is the release process also flexible?

As for the discussion about who reviews changes, I would expect anyone interested in our guidelines to be following the guide-dev list. Changes to the guide are always reviewed by at least someone - someone must actively agree to the change before it goes in. And even after the change has gone in there is an extra step where "bad changes" can be caught since the final web-based version is not pulled automatically from GitHub, but goes through "release testing" and is manually released to the webserver. Anyone can edit a JEP at any time. I think that anyone interested in our rules should be watching these JEPs in JBS as well, but still the notification only arrives after the fact and someone must actively undo the change. In both cases changes are only reviewed by people who opt-in to the process.

/Jesper

> On 26 Jun 2020, at 16:13, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> wrote:
> 
> Mark, Andreas, Jesper,
> 
> First of all, I think this question is of far too much importance to discuss only for the reviewers on guide-dev, so I'm widening the scope to include jdk-dev. I am certainly not alone in thinking that having the Style Guidelines was a major part of what the Developer's Guide Project was all about.
> 
> Secondly, for some reason, I have not gotten any further emails from this code review. :-( Possibly it's related to the many hiccups of the ojn mailing list server lately. I have tried quoting part of Mark's comment here by copying it from GitHub. I apologize if the formatting is a bit odd due to this.
>> No matter what we say about these documents merely being suggestive guidelines, at least some people will treat them as normative and authoritative, and use them as the basis for arguing one way or another.
> I do not agree that this is a valid argument. We can't claim that we should not publish guidelines, since some people will not understand what "guidelines" mean. If you are serious about this argument, then we can just as well shut down the entire Developer's Guide, since it's all about non-authoritative suggestions.
> 
> The fact that "some people can misunderstand" is hardly ever a good reason not to provide information that is highly useful to the vast majority who do not misunderstand.
>> A Java style guide published in the OpenJDK Community will also be used by people in the broader ecosystem who will never contribute to the JDK, but who?ve been asking us for years for an updated style guide for use in their own work. We should therefore try to take extra care with it.
> Oh, really? We missed that train years ago. If we had published updated style guides when everybody was screaming for it, we could have had an impact on the wider Java community. But we did not, and our official style rules slid into oblivion.
> 
> That crown position has been taking mostly by Google's Java Style Guide [1].
> 
> We might be able to restore our position as a beacon to the rest of the Java community, or we might not. I'm not even sure if it is a good thing for the OpenJDK community as such if our internal processes are governed in fear of making a mess for a group of unknown outsiders.
> 
> And even if we do think it is desirable, for every year we wait until we publish a guide, the harder it will become to create a new, globally recognized, normative style guide.
>> So, I don?t think code style guidelines belong in the Developer?s Guide, even if they are just ?guidelines.
>> [...]
>> An authoritative document, by contrast, should be fairly stable, and changes to it should be subject to broad review so that it represents a rough consensus of JDK contributors rather than that of a smaller group of Guide contributors.
>> [...]
>> Fortunately we already have an established means of building consensus around authoritative documents, namely the JEP process. I suggest that code style guides be published as informational JEPs, alongside existing prominent JEPs such as those for the release process, incubator modules, and so forth.
> First of all, I wholeheartedly object to the view presented here that the JEP process is an inclusive and democratic way of bringing the OpenJDK community forward.
> 
> On the contrast, JEPs tend to mostly be authoritative documents written by the authors and endorsers, and feedback from the community is all-too-often ignored. There is no way an outsider can submit a patch to a JEP and have it reviewed, discussed, and/or accepted. Instead, anyone objecting to a JEP will need to communicate their sentiment on the mailing list, and watching the authors of the JEP get inspired by it, or ignore it, all at their own will. There is no voting about JEPs. Non-informational JEPs give the wider community a choice to come with "reasonable objects", but that is only a binary choice on a completed proposal, and it does not even apply to Informational JEPs that are supposed to be continuously updated.
> 
> I do not want to go into a discussion if this is a method that works well for planned features in the JDK (let's assume so for now, and save that question for a rainy day!). But it is certainly not a process that is any more inclusive than having the Style Guide as a project on Github. On the contrast, here any OpenJDK Member is free to publish a patch, and have it discussed, in the open, by all other members. If anything, the error in this process lies in the unfortunate fact that not all OpenJDK Members were made initial Reviewers of the Guide Project.
> 
> Finally, I want to bring notice to the fact that Andreas' proposal for a Style Guide was ready, with basically the same contents that are being proposed here, in 2015. That is 5 years ago! For all this time we have been without any written document to guide us, formal or informal. If you believe a JEP had been the best way forward in this issue, as the JDK Team Lead you have had ample of time to get that ball rolling.
> 
> If you want to create an Informational JEP, with an authoritative style guide, fine, go ahead. But, in the meantime, do not block the Developer's Guide from having a written document to help and support the actual developers that struggle everyday with trying to write good, readable code, or for that matter, reviewers who are in need of guidance of what to accept or reject, or who have to repeat, over and over again, to newcomers how code is supposed to look to be accepted.
> 
> The lack of this document does not mean that "anything goes". It just makes the knowledge invisibly buried in the heads of a few developers and reviewers, were it cannot be easily shared, and where it steals precious time from said developers in repeating these rules over and over in reviews.
> 
> My suggestion to resolving these conflicting views on what the code style guideline should be, by adding a large header to the document with something like: "This is a non-authoritative document, and is considered an interim solution. An Informational JEP with the purpose of being a formal, authoritative document for the Style Guide is being worked upon, and will fully replace this document when it is completed."
> 
> /Magnus
> 
> [1] https://google.github.io/styleguide/javaguide.html
> 


From mark.reinhold at oracle.com  Fri Jun 26 19:17:35 2020
From: mark.reinhold at oracle.com (mark.reinhold at oracle.com)
Date: Fri, 26 Jun 2020 12:17:35 -0700
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
Message-ID: <20200626121735.173915279@eggemoggin.niobe.net>

For context, here is the message from me to which Magnus replied.

- Mark

----

From: mark.reinhold at oracle.com
To: jesper.wilhelmsson at oracle.com
Cc: Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>,
 guide-dev at openjdk.java.net
Subject: Re: RFR: Updated section on Code Conventions.
Date: Thu 2020/06/25 16:51:30 -0700

2020/6/22 10:42:46 -0700, jesper.wilhelmsson at oracle.com:
>> On 22 Jun 2020, at 18:40, mark.reinhold at oracle.com wrote:
>> 
>> 2020/6/18 6:10:21 -0700, Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>:
>>> Pull request for adding code conventions.
>> 
>> Thanks for contributing this material, but I don?t think that the
>> Developers? Guide is the right place for it.
>> 
>> If we have agreed policies about coding style then we should treat
>> them as authoritative, normative information.  As such, they?d be
>> out of place in a Guide that?s meant only to contain tutorials and
>> suggestions.
> 
> I guess there are two ways to look at it - either these are coding
> style guidelines, or they are authoritative coding style rules. My
> impression was the former, that they were guidelines, and as such I
> think the Guide is the right place for them. If these are to be
> treated as authoritative rules however I agree, the Guide is not the
> place for them. In that case we should make sure these are published
> in the right place asap and just have the Guide link to them.

For better or for worse, code style is often a topic of much -- and
sometimes heated -- debate.  No matter what we say about these documents
merely being suggestive guidelines, at least some people will treat them
as normative and authoritative, and use them as the basis for arguing
one way or another.

The Developers? Guide is meant to be a living document, written by its
contributors to help others more easily contribute to the JDK.  As such
it can change at any time.  Changes to it are, moreover, not broadly
reviewed, so it does not necessarily represent a consensus of JDK
contributors.

An authoritative document, by contrast, should be fairly stable, and
changes to it should be subject to broad review so that it represents a
rough consensus of JDK contributors rather than that of a smaller group
of Guide contributors.

A Java style guide published in the OpenJDK Community will also be used
by people in the broader ecosystem who will never contribute to the JDK,
but who?ve been asking us for years for an updated style guide for use
in their own work.  We should therefore try to take extra care with it.

So, I don?t think code style guidelines belong in the Developer?s Guide,
even if they are just ?guidelines.?

> What would be the right place to put coding style rules?

Good question!

Fortunately we already have an established means of building consensus
around authoritative documents, namely the JEP process.  I suggest that
code style guides be published as informational JEPs, alongside existing
prominent JEPs such as those for the release process, incubator modules,
and so forth.

The JEP process and the infrastructure it rests on (JBS) aren?t perfect.
Maintaining long documents in JBS issues, in particular, is painful, and
the JBS Markdown renderer is bonkers.  With a little hacking, however, I
think we can arrange for better revision control and rendering of select
JEPs.

- Mark

From joe.darcy at oracle.com  Sat Jun 27 01:37:44 2020
From: joe.darcy at oracle.com (Joe Darcy)
Date: Fri, 26 Jun 2020 18:37:44 -0700
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <E4761514-8D52-4BA6-A93B-C4A7701CD90D@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
 <A2CF77F1-08D0-46E4-BD8B-428F09A9448A@oracle.com>
 <E4761514-8D52-4BA6-A93B-C4A7701CD90D@oracle.com>
Message-ID: <cb8589a8-d92c-615a-4f25-3eb0371260ac@oracle.com>

On 6/26/2020 10:54 AM, Brian Goetz wrote:
> While this is not a direct answer to your question, I do have a secondary interest in the existence of a ?style guide?, whether or not it is considered mandatory for OpenJDK code.
>
> Why did Andreas undertake the (almost certainly thankless) task of updating the style guide in the first place?  Because it was ?out of date?.  What does that mean?  I think two main things:
>
>      - There were some overly fussy guidelines that came from the very early days (?sort field names by Levenstein distance from 'foo??) that the passage of time had revealed to be a silly waste of effort;
>      - The language had evolved significantly since the guidelines were written, and so there were many language features that were not covered by the style guidelines.
>
> As the stewards of the Java language, we have an opportunity to get Java developers off on the right foot using new language features ? if we provide reasonable style and usage information for them.  Having good initial advice will reduce the time it takes to equilibrate on usage patterns, as well as eliminating gratuitously multimodal distributions of usages.  But, the window for doing so is small before everyone chooses their own style for indenting, say, enum constant lists.
>
> To the extent that it forms a ?from the source? set of recommendations for new language features (which are coming fast and furious these days!), a non-authoritative guide still has significant value.
>

As a concrete example, such a style guide would provide a natural and 
more discoverable home for useful documents like Stuart's

 ??? "Local Variable Type Inference: Style Guidelines"
 ??? https://openjdk.java.net/projects/amber/LVTIstyle.html

-Joe


From jesper.wilhelmsson at oracle.com  Sat Jun 27 08:21:35 2020
From: jesper.wilhelmsson at oracle.com (Jesper Wilhelmsson)
Date: Sat, 27 Jun 2020 10:21:35 +0200
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <f097ceb3-0270-bdcc-d720-cf121d012ef1@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
 <f097ceb3-0270-bdcc-d720-cf121d012ef1@oracle.com>
Message-ID: <A27ADB98-09CF-4C9A-B973-9C6D1FEDF0B1@oracle.com>



> On 27 Jun 2020, at 00:42, Alex Buckley <alex.buckley at oracle.com> wrote:
> 
> The CfV for the Developer's Guide Project said: "The OpenJDK Developer's Guide is intended to contain tutorial style texts that give examples and step-by step directions for common parts of the development process. Strict rules for OpenJDK development are better suited to a process JEP. The development of such a JEP is outside of the scope of this project but will be developed as part of a separate effort in parallel."

That is only part of the mail. It also linked to the OpenJDK wiki with a reference to the process related information that has been posted there.

> With that in mind, some thoughts:
> 
> 1. The OpenJDK Bylaws define "social infrastructure" -- roles, voting, groups, projects. Where is the definition of "technical infrastructure" -- repositories, bug trackers, mailing lists, test fleets? Answer: Locked up in the current OpenJDK Developer's Guide. It seems to me that a good start would be: throw all the chapters in the current Guide up in the air, and catch only the ones which let you write a dry, factual manual about the technical infrastructure. Such a manual relies on the social infrastructure from the Bylaws, notably the idea of a Project. The manual is not "normative" in the sense of "using wise judgment to establish a standard that people must follow". Accordingly, it does not describe processes (e.g. CSR) or conventions (e.g. code style, or how-many-changesets-to-become-Committer). Nor is the manual "informative" in the sense of giving tutorials, discussion, or rationale about a normative artifact. It's definitional, like the Bylaws.

There are parts like this in the current guide and there will be more of this kind going forward. The mailing lists recently got a new description [0]. It hasn't been released to the webserver yet, but it's in GitHub.

> 
> 2. Now turn to normative processes that use the technical infrastructure: filing a bug, producing and shepherding a changeset, ensuring compatibility using CSR, etc. For these topics, there is established behavior that every OpenJDK Participant must follow. It seems to me that this is what the CfV really wanted to document with "tutorial style texts". By all means present the process of filing a bug as a tutorial, but don't pretend it's merely a "non-authoritative suggestion". There is plainly a right way, a norm, an authoritative suggestion when it comes to filing a bug, or formatting a changeset comment, or thinking about the source/binary/behavioral compatibility of a change.

I agree that there is "a right way" to do many of these things, and yes this is the kind of texts that I referred to as "tutorial style texts".

> 
> 3. Now turn to informative content that every OpenJDK Participant is free to ignore without consequence. I think you're saying that this could include non-authoritative suggestions about the formatting of Java source code in an OpenJDK repository. However, I agree with Mark: any document connected with Oracle that concerns Java code formatting will be taken as normative, authoritative rules by a broad swathe of the worldwide Java developer community. I can tell you 20 ways that people will interpret your content as "Oracle's Official Java Coding Guidelines". (Example: "In this article on $DEVELOPER_NEWS_SITE, we examine Oracle's new coding guide, and see how it compares with guides from Google and Alibaba!" -- the writer is incentivized to get views, not to make Magnus happy with how the guidelines are characterized.) Is there some other content that can uncontroversially be labelled as informative? "A Year In The Life Of A HotSpot Bug" ? "Advice On Starting A Port, as told by Dalibor Topic" ?

I'm not sure that I have any good examples of "informative content that every OpenJDK Participant is free to ignore without consequence", that would as you exemplifies here be just stories. I'm not even sure how to interpret the word "informative" here since our process JEPs which are clearly meant to be followed strictly are "informative JEPs". However I don't think that the coding style guide fits in this category because it's not a document that can be ignored without consequence. Even if it's not meant to be strict rules, it's still meant to be followed where there are no good reason to do something else. This is basically at the same level as many of our other guides for how to do things like filing a bug, backing out a changeset, problemlist stuff [1], or the JBS Label Dictionary [2] all of which are things I intend to move into the Guide in some form. Or how to use noreg-labels in JBS (which has been in the Guide since the start [3]). The JBS Label Dictionary was actually the page that started this whole discussion that eventually lead to creating the Developers' Guide Project.

I agree that there will be people taking the style guide as normative regardless where we publish it, but I don't think we should allow peoples misconceptions to decide how or where we publish our documentation. "we" and "our" here by the way refer to the OpenJDK community, not Oracle. The Developers' Guide is an OpenJDK project, not an Oracle project. Anyone calling these "Oracle's Official Java Coding Guidelines" would just be plain wrong. The author of the text who is also contributing it isn't even employed by Oracle. Oracle's official Java coding guidelines are here [4]. This is the style that all Oracle employees should use for their Java code unless we have our own style guide.

I'm sure some blog or article will present comparisons like the one you mention. If they call it Oracle we should correct them. Besides that I don't see any harm in an article comparing this to the Google and Alibaba guides. If anything it will just bring more traffic to our guide and spread the word that this is becoming a document worth paying attention to. (Hopefully that won't happen until the rest of the Guide has more content.)

/Jesper

[0] https://github.com/openjdk/guide/blob/master/src/mailingLists.md
[1] https://wiki.openjdk.java.net/display/HotSpot/HotSpot+How+To
[2] https://wiki.openjdk.java.net/display/HotSpot/JBS+Label+Dictionary
[3] https://openjdk.java.net/guide/changePlanning.html#noreg
[4] https://www.oracle.com/java/technologies/javase/codeconventions-introduction.html

> 
> Alex
> 
> On 6/26/2020 7:13 AM, Magnus Ihse Bursie wrote:
>> Mark, Andreas, Jesper,
>> First of all, I think this question is of far too much importance to discuss only for the reviewers on guide-dev, so I'm widening the scope to include jdk-dev. I am certainly not alone in thinking that having the Style Guidelines was a major part of what the Developer's Guide Project was all about.
>> Secondly, for some reason, I have not gotten any further emails from this code review. :-( Possibly it's related to the many hiccups of the ojn mailing list server lately. I have tried quoting part of Mark's comment here by copying it from GitHub. I apologize if the formatting is a bit odd due to this.
>>> No matter what we say about these documents merely being suggestive guidelines, at least some people will treat them as normative and authoritative, and use them as the basis for arguing one way or another.
>> I do not agree that this is a valid argument. We can't claim that we should not publish guidelines, since some people will not understand what "guidelines" mean. If you are serious about this argument, then we can just as well shut down the entire Developer's Guide, since it's all about non-authoritative suggestions.
>> The fact that "some people can misunderstand" is hardly ever a good reason not to provide information that is highly useful to the vast majority who do not misunderstand.
>>> A Java style guide published in the OpenJDK Community will also be used by people in the broader ecosystem who will never contribute to the JDK, but who?ve been asking us for years for an updated style guide for use in their own work. We should therefore try to take extra care with it.
>> Oh, really? We missed that train years ago. If we had published updated style guides when everybody was screaming for it, we could have had an impact on the wider Java community. But we did not, and our official style rules slid into oblivion.
>> That crown position has been taking mostly by Google's Java Style Guide [1].
>> We might be able to restore our position as a beacon to the rest of the Java community, or we might not. I'm not even sure if it is a good thing for the OpenJDK community as such if our internal processes are governed in fear of making a mess for a group of unknown outsiders.
>> And even if we do think it is desirable, for every year we wait until we publish a guide, the harder it will become to create a new, globally recognized, normative style guide.
>>> So, I don?t think code style guidelines belong in the Developer?s Guide, even if they are just ?guidelines.
>>> [...]
>>> An authoritative document, by contrast, should be fairly stable, and changes to it should be subject to broad review so that it represents a rough consensus of JDK contributors rather than that of a smaller group of Guide contributors.
>>> [...]
>>> Fortunately we already have an established means of building consensus around authoritative documents, namely the JEP process. I suggest that code style guides be published as informational JEPs, alongside existing prominent JEPs such as those for the release process, incubator modules, and so forth.
>> First of all, I wholeheartedly object to the view presented here that the JEP process is an inclusive and democratic way of bringing the OpenJDK community forward.
>> On the contrast, JEPs tend to mostly be authoritative documents written by the authors and endorsers, and feedback from the community is all-too-often ignored. There is no way an outsider can submit a patch to a JEP and have it reviewed, discussed, and/or accepted. Instead, anyone objecting to a JEP will need to communicate their sentiment on the mailing list, and watching the authors of the JEP get inspired by it, or ignore it, all at their own will. There is no voting about JEPs. Non-informational JEPs give the wider community a choice to come with "reasonable objects", but that is only a binary choice on a completed proposal, and it does not even apply to Informational JEPs that are supposed to be continuously updated.
>> I do not want to go into a discussion if this is a method that works well for planned features in the JDK (let's assume so for now, and save that question for a rainy day!). But it is certainly not a process that is any more inclusive than having the Style Guide as a project on Github. On the contrast, here any OpenJDK Member is free to publish a patch, and have it discussed, in the open, by all other members. If anything, the error in this process lies in the unfortunate fact that not all OpenJDK Members were made initial Reviewers of the Guide Project.
>> Finally, I want to bring notice to the fact that Andreas' proposal for a Style Guide was ready, with basically the same contents that are being proposed here, in 2015. That is 5 years ago! For all this time we have been without any written document to guide us, formal or informal. If you believe a JEP had been the best way forward in this issue, as the JDK Team Lead you have had ample of time to get that ball rolling.
>> If you want to create an Informational JEP, with an authoritative style guide, fine, go ahead. But, in the meantime, do not block the Developer's Guide from having a written document to help and support the actual developers that struggle everyday with trying to write good, readable code, or for that matter, reviewers who are in need of guidance of what to accept or reject, or who have to repeat, over and over again, to newcomers how code is supposed to look to be accepted.
>> The lack of this document does not mean that "anything goes". It just makes the knowledge invisibly buried in the heads of a few developers and reviewers, were it cannot be easily shared, and where it steals precious time from said developers in repeating these rules over and over in reviews.
>> My suggestion to resolving these conflicting views on what the code style guideline should be, by adding a large header to the document with something like: "This is a non-authoritative document, and is considered an interim solution. An Informational JEP with the purpose of being a formal, authoritative document for the Style Guide is being worked upon, and will fully replace this document when it is completed."
>> /Magnus
>> [1] https://google.github.io/styleguide/javaguide.html


From brian.goetz at oracle.com  Fri Jun 26 17:54:32 2020
From: brian.goetz at oracle.com (Brian Goetz)
Date: Fri, 26 Jun 2020 13:54:32 -0400
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <A2CF77F1-08D0-46E4-BD8B-428F09A9448A@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
 <A2CF77F1-08D0-46E4-BD8B-428F09A9448A@oracle.com>
Message-ID: <E4761514-8D52-4BA6-A93B-C4A7701CD90D@oracle.com>

While this is not a direct answer to your question, I do have a secondary interest in the existence of a ?style guide?, whether or not it is considered mandatory for OpenJDK code.  

Why did Andreas undertake the (almost certainly thankless) task of updating the style guide in the first place?  Because it was ?out of date?.  What does that mean?  I think two main things: 

    - There were some overly fussy guidelines that came from the very early days (?sort field names by Levenstein distance from 'foo??) that the passage of time had revealed to be a silly waste of effort;
    - The language had evolved significantly since the guidelines were written, and so there were many language features that were not covered by the style guidelines.  

As the stewards of the Java language, we have an opportunity to get Java developers off on the right foot using new language features ? if we provide reasonable style and usage information for them.  Having good initial advice will reduce the time it takes to equilibrate on usage patterns, as well as eliminating gratuitously multimodal distributions of usages.  But, the window for doing so is small before everyone chooses their own style for indenting, say, enum constant lists.  

To the extent that it forms a ?from the source? set of recommendations for new language features (which are coming fast and furious these days!), a non-authoritative guide still has significant value.  

> On Jun 26, 2020, at 11:41 AM, Jesper Wilhelmsson <jesper.wilhelmsson at oracle.com> wrote:
> 
> I'll only quote a part of Magnus' mail here because to me there really is only one question: Is the style guide an authoritative set of rules or is it a guide with suggestions?
> 
>>> No matter what we say about these documents merely being suggestive guidelines, at least some people will treat them as normative and authoritative, and use them as the basis for arguing one way or another.
>> I do not agree that this is a valid argument. We can't claim that we should not publish guidelines, since some people will not understand what "guidelines" mean. If you are serious about this argument, then we can just as well shut down the entire Developer's Guide, since it's all about non-authoritative suggestions.
>> 
>> The fact that "some people can misunderstand" is hardly ever a good reason not to provide information that is highly useful to the vast majority who do not misunderstand.
> 
> I agree with Magnus here, we can't treat it as a set of rules if it isn't a set of rules. I'm totally fine with placing it in a JEP if these are rules, but that also means that everyone are expected to follow these rules, and I'm sure that will result in a lot more policing than we see today.
> 
> If the style guide is what it's called, a guide, then having it in a JEP will actually cause more damage since it will not only be a few people who mistakenly treat it as a set of rules, it will actually look like a set of rules for the vast majority of the readers. The Developers' Guide will even (at least with the current wording) say that it is a set of rules, "The formal rules and processes are described in other documents, like JEP 1 ..., or JEP 3...".
> 
> The current wording of the style guide clearly states that it's a guide with suggestions in several places throughout the text and at least everyone I have spoken to about style guides have agreed that these should not dictate a fix set of rules that may never be broken but should rather be guidelines with flexibility when needed. If this is a JEP that is flexible, how will that affect other JEPs? Is the release process also flexible?
> 
> As for the discussion about who reviews changes, I would expect anyone interested in our guidelines to be following the guide-dev list. Changes to the guide are always reviewed by at least someone - someone must actively agree to the change before it goes in. And even after the change has gone in there is an extra step where "bad changes" can be caught since the final web-based version is not pulled automatically from GitHub, but goes through "release testing" and is manually released to the webserver. Anyone can edit a JEP at any time. I think that anyone interested in our rules should be watching these JEPs in JBS as well, but still the notification only arrives after the fact and someone must actively undo the change. In both cases changes are only reviewed by people who opt-in to the process.
> 
> /Jesper
> 
>> On 26 Jun 2020, at 16:13, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> wrote:
>> 
>> Mark, Andreas, Jesper,
>> 
>> First of all, I think this question is of far too much importance to discuss only for the reviewers on guide-dev, so I'm widening the scope to include jdk-dev. I am certainly not alone in thinking that having the Style Guidelines was a major part of what the Developer's Guide Project was all about.
>> 
>> Secondly, for some reason, I have not gotten any further emails from this code review. :-( Possibly it's related to the many hiccups of the ojn mailing list server lately. I have tried quoting part of Mark's comment here by copying it from GitHub. I apologize if the formatting is a bit odd due to this.
>>> No matter what we say about these documents merely being suggestive guidelines, at least some people will treat them as normative and authoritative, and use them as the basis for arguing one way or another.
>> I do not agree that this is a valid argument. We can't claim that we should not publish guidelines, since some people will not understand what "guidelines" mean. If you are serious about this argument, then we can just as well shut down the entire Developer's Guide, since it's all about non-authoritative suggestions.
>> 
>> The fact that "some people can misunderstand" is hardly ever a good reason not to provide information that is highly useful to the vast majority who do not misunderstand.
>>> A Java style guide published in the OpenJDK Community will also be used by people in the broader ecosystem who will never contribute to the JDK, but who?ve been asking us for years for an updated style guide for use in their own work. We should therefore try to take extra care with it.
>> Oh, really? We missed that train years ago. If we had published updated style guides when everybody was screaming for it, we could have had an impact on the wider Java community. But we did not, and our official style rules slid into oblivion.
>> 
>> That crown position has been taking mostly by Google's Java Style Guide [1].
>> 
>> We might be able to restore our position as a beacon to the rest of the Java community, or we might not. I'm not even sure if it is a good thing for the OpenJDK community as such if our internal processes are governed in fear of making a mess for a group of unknown outsiders.
>> 
>> And even if we do think it is desirable, for every year we wait until we publish a guide, the harder it will become to create a new, globally recognized, normative style guide.
>>> So, I don?t think code style guidelines belong in the Developer?s Guide, even if they are just ?guidelines.
>>> [...]
>>> An authoritative document, by contrast, should be fairly stable, and changes to it should be subject to broad review so that it represents a rough consensus of JDK contributors rather than that of a smaller group of Guide contributors.
>>> [...]
>>> Fortunately we already have an established means of building consensus around authoritative documents, namely the JEP process. I suggest that code style guides be published as informational JEPs, alongside existing prominent JEPs such as those for the release process, incubator modules, and so forth.
>> First of all, I wholeheartedly object to the view presented here that the JEP process is an inclusive and democratic way of bringing the OpenJDK community forward.
>> 
>> On the contrast, JEPs tend to mostly be authoritative documents written by the authors and endorsers, and feedback from the community is all-too-often ignored. There is no way an outsider can submit a patch to a JEP and have it reviewed, discussed, and/or accepted. Instead, anyone objecting to a JEP will need to communicate their sentiment on the mailing list, and watching the authors of the JEP get inspired by it, or ignore it, all at their own will. There is no voting about JEPs. Non-informational JEPs give the wider community a choice to come with "reasonable objects", but that is only a binary choice on a completed proposal, and it does not even apply to Informational JEPs that are supposed to be continuously updated.
>> 
>> I do not want to go into a discussion if this is a method that works well for planned features in the JDK (let's assume so for now, and save that question for a rainy day!). But it is certainly not a process that is any more inclusive than having the Style Guide as a project on Github. On the contrast, here any OpenJDK Member is free to publish a patch, and have it discussed, in the open, by all other members. If anything, the error in this process lies in the unfortunate fact that not all OpenJDK Members were made initial Reviewers of the Guide Project.
>> 
>> Finally, I want to bring notice to the fact that Andreas' proposal for a Style Guide was ready, with basically the same contents that are being proposed here, in 2015. That is 5 years ago! For all this time we have been without any written document to guide us, formal or informal. If you believe a JEP had been the best way forward in this issue, as the JDK Team Lead you have had ample of time to get that ball rolling.
>> 
>> If you want to create an Informational JEP, with an authoritative style guide, fine, go ahead. But, in the meantime, do not block the Developer's Guide from having a written document to help and support the actual developers that struggle everyday with trying to write good, readable code, or for that matter, reviewers who are in need of guidance of what to accept or reject, or who have to repeat, over and over again, to newcomers how code is supposed to look to be accepted.
>> 
>> The lack of this document does not mean that "anything goes". It just makes the knowledge invisibly buried in the heads of a few developers and reviewers, were it cannot be easily shared, and where it steals precious time from said developers in repeating these rules over and over in reviews.
>> 
>> My suggestion to resolving these conflicting views on what the code style guideline should be, by adding a large header to the document with something like: "This is a non-authoritative document, and is considered an interim solution. An Informational JEP with the purpose of being a formal, authoritative document for the Style Guide is being worked upon, and will fully replace this document when it is completed."
>> 
>> /Magnus
>> 
>> [1] https://google.github.io/styleguide/javaguide.html
>> 
> 


From aph at redhat.com  Mon Jun 29 09:21:21 2020
From: aph at redhat.com (Andrew Haley)
Date: Mon, 29 Jun 2020 10:21:21 +0100
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
Message-ID: <a922398b-b7d8-d45b-bcbf-dbeb1517de02@redhat.com>

Hi,

On 26/06/2020 15:13, Magnus Ihse Bursie wrote:
>
> First of all, I think this question is of far too much importance to
> discuss only for the reviewers on guide-dev, so I'm widening the scope
> to include jdk-dev. I am certainly not alone in thinking that having the
> Style Guidelines was a major part of what the Developer's Guide Project
> was all about.

Thank you for doing that.

> On 2020-06-22 18:40, mark.reinhold at oracle.com wrote:
>> No matter what we say about these documents merely being suggestive
>> guidelines, at least some people will treat them as normative and
>> authoritative, and use them as the basis for arguing one way or another.
>
> I do not agree that this is a valid argument. We can't claim that we
> should not publish guidelines, since some people will not understand
> what "guidelines" mean. If you are serious about this argument, then
> we can just as well shut down the entire Developer's Guide, since
> it's all about non-authoritative suggestions.

Mark's point, and I hope I'm not misrepresenting him, is that figuring
out what the coding style should be, without being over-prescriptive,
is difficult and requires a JEP. Putting non-authoritative Java style
guidelines in the Developers? Guide risks bypassing any review
process.

> And even if we do think it is desirable, for every year we wait
> until we publish a guide, the harder it will become to create a new,
> globally recognized, normative style guide.

True, but a nonexistent style guide is far better than one which in
effect constrains developers and reviewers in such a way as to make
working on the JDK worse, in terms of both the experience for the
developer and the outcome.

> First of all, I wholeheartedly object to the view presented here
> that the JEP process is an inclusive and democratic way of bringing
> the OpenJDK community forward.
>
> On the contrast, JEPs tend to mostly be authoritative documents
> written by the authors and endorsers, and feedback from the
> community is all-too-often ignored.

Be that as it may, it's not a reason to publish non-authoritative
style guidelines either.

> My suggestion to resolving these conflicting views on what the code
> style guideline should be, by adding a large header to the document
> with something like: "This is a non-authoritative document, and is
> considered an interim solution. An Informational JEP with the
> purpose of being a formal, authoritative document for the Style
> Guide is being worked upon, and will fully replace this document
> when it is completed."

But for that to happen, you have to have some agreement about what
then code style guidelines in a Developers' Guide should be.

-- 
Andrew Haley  (he/him)
Java Platform Lead Engineer
Red Hat UK Ltd. <https://www.redhat.com>
https://keybase.io/andrewhaley
EAC8 43EB D3EF DB98 CC77 2FAD A5CD 6035 332F A671


From alex.buckley at oracle.com  Mon Jun 29 17:45:26 2020
From: alex.buckley at oracle.com (Alex Buckley)
Date: Mon, 29 Jun 2020 10:45:26 -0700
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: <A27ADB98-09CF-4C9A-B973-9C6D1FEDF0B1@oracle.com>
References: <AzLIGMF9Q7CY4um6O3kB1mtSzGhwice0SaHF65bQlwI=.b38f3bb4-da27-45ab-8a10-922af7414ef1@github.com>
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 <f3dd9f7b-e1e0-b37e-8363-580f5cb0cf64@oracle.com>
 <f097ceb3-0270-bdcc-d720-cf121d012ef1@oracle.com>
 <A27ADB98-09CF-4C9A-B973-9C6D1FEDF0B1@oracle.com>
Message-ID: <ba46f487-fe3a-e6d9-f00e-1f009669bb39@oracle.com>

On 6/27/2020 1:21 AM, Jesper Wilhelmsson wrote:
>> On 27 Jun 2020, at 00:42, Alex Buckley <alex.buckley at oracle.com 
>> <mailto:alex.buckley at oracle.com>> wrote:
>> 1. The OpenJDK Bylaws define "social infrastructure" -- roles, voting, 
>> groups, projects. Where is the definition of "technical 
>> infrastructure" -- repositories, bug trackers, mailing lists, test 
>> fleets? Answer: Locked up in the current OpenJDK Developer's Guide. It 
>> seems to me that a good start would be: throw all the chapters in the 
>> current Guide up in the air, and catch only the ones which let you 
>> write a dry, factual manual about the technical infrastructure. Such a 
>> manual relies on the social infrastructure from the Bylaws, notably 
>> the idea of a Project. ...
> 
> There are parts like this in the current guide and there will be more of 
> this kind going forward. The mailing lists recently got a new 
> description [0]. It hasn't been released to the webserver yet, but it's 
> in GitHub.

Yes, I saw mailingLists.md, but it and the other RFRs on guide-dev are 
all bottom-up changes that preserve the oddball structure of the current 
Guide. I'm suggesting top-down changes -- write out a new Table Of 
Contents so as to categorize (1) the normative, uncontroversial content 
about technical infrastructure (e.g., mailing list suffixes); (2) the 
normative, controversial content about development practices where (say) 
different Projects have different views and you need to set expectations 
in general; and (3) informative background material (e.g. timeline of 
feature releases by the JDK Project; history of leadership in the JDK 
6/7u/8u Projects).

> I'm not sure that I have any good examples of "informative content that 
> every OpenJDK Participant is free to ignore without consequence", that 
> would as you exemplifies here be just stories. I'm not even sure how to 
> interpret the word "informative" here since our process JEPs which are 
> clearly meant to be followed strictly are "informative JEPs". 

To clarify: a "Process JEP" is normative. JEP 3: JDK Release Process is 
a Process JEP because it authoritatively describes a protocol which must 
be followed.

An "Informational JEP" is harder to characterize. Despite the name 
suggesting informative status, the reality is that almost all 
Informational JEPs are normative policy documents:

- JEP 11: Incubator Modules
- JEP 12: Preview Language and VM Features
- JEP 182: Policy for Retiring javac -source and -target Options
- JEP 293: Guidelines for JDK Command-Line Tool Options
- JEP draft: javadoc tags to distinguish API, implementation, 
specification, and notes
- JEP draft: Disable experimental features by default
- JEP draft: Guidelines for documenting system properties
- JEP draft: Keyword Management for the Java Language

(A document can be normative even if the penalty for non-conformance is 
softer than the hard-edged JLS penalty of "A compile-time error occurs 
...". For example, the penalty for not following the guidelines for 
documenting system properties might be more time spent on getting your 
changeset accepted, as you seek to convince Reviewers that your system 
properties really are special and you really do know what you're doing. 
The only Informational JEP which is strictly informative is JEP 188: 
Java Memory Model Update.)

I'm not sure if Mark if saying this exactly, but I can see the 
Informational-means-normative angle serving as a feature, not a bug. An 
Informational JEP "Java Style Guide for OpenJDK Projects" which is 
normative for OpenJDK Projects will be taken as normative for ordinary 
Java programs around the world, but the JEP "wrapper" is a great 
mechanism for stopping outright misrepresentation and confusion.

Alex