From stuart.marks at oracle.com Wed Jul 1 05:23:08 2020 From: stuart.marks at oracle.com (Stuart Marks) Date: Tue, 30 Jun 2020 22:23:08 -0700 Subject: RFR: Updated section on Code Conventions. In-Reply-To: References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> Message-ID: <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> On 6/26/20 6:37 PM, Joe Darcy wrote: > On 6/26/2020 10:54 AM, Brian Goetz wrote: >> 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 Thanks for mentioning this, Joe. To this I'd add Jim Laskey's document, Programmer's Guide To Text Blocks https://cr.openjdk.java.net/~jlaskey/Strings/TextBlocksGuide_v9.html I will quibble here with Brian's intimation that these documents are not authoritative. I would argue that being "from the source" implies that the documents *are* authoritative. They were written by people very close to the development of the features themselves, and as such are in the best position to give informed advice about proper and improper use, avoidance of pitfalls, recommended practices, and so forth. With this in mind, I will state that I do not think the Java Style Guide belongs in the Developer's Guide. The reason is that the documents have fundamentally different editorial stances. The Developer's Guide is primarily operational: it contains information about how to do things, where to look, whom to ask, step by step procedures to follow, tips & tricks for working effectively, and so forth. It covers a wide range of topic areas. For example, one tip might be To switch branches, use 'git switch' instead of 'git checkout -b'. Git experts might reasonably take issue with this advice. However, git experts might not have any opinion at all on other topics, such as one that covers the proper usage of the noreg-long label on a JBS issue. As such, the Developer's Guide benefits from input from many individuals with a broad range of interests, each contributing bits of expertise in different areas. A style guide is fundamentally different. To be useful, it must be authoritative -- as mentioned above -- and it also must be highly cohesive. It needs to have a uniform editorial voice that is adhered to consistently throughout the document. For example, it might take a prescriptive vs. a descriptive stance, or it might choose a vocabulary for recommendations of varying strength ("can", "should", "must", etc.) and use that throughout the document. As such, a style guide is not at all amenable to a "crowdsourcing" approach and must be edited by a handful of individuals. Since the editorial approach for the style guide material is so different from that of the Developer's Guide, it follows that the style guide should be a different document. Personally I'm agnostic to the exact process for delivering a style guide. If Mark thinks a JEP is required, then maybe that's the best way forward. But I could imagine other paths forward that wouldn't use a JEP. I would strongly recommend against making the style guide itself be a JEP. Today, editing a JEP with more than a page or two of text is already unwieldy. It's easy to introduce errors inadvertently, and history tracking is virtually nonexistent. It seems unwise to put JIRA+markdown plugin improvements into the critical path of delivering a style guide. Doing that might prove fatal. s'marks From magnus.ihse.bursie at oracle.com Wed Jul 1 08:44:03 2020 From: magnus.ihse.bursie at oracle.com (Magnus Ihse Bursie) Date: Wed, 1 Jul 2020 10:44:03 +0200 Subject: RFR: Updated section on Code Conventions. In-Reply-To: <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> Message-ID: On 2020-07-01 07:23, Stuart Marks wrote: > > > On 6/26/20 6:37 PM, Joe Darcy wrote: >> On 6/26/2020 10:54 AM, Brian Goetz wrote: >>> 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 > > Thanks for mentioning this, Joe. To this I'd add Jim Laskey's document, > > ????Programmer's Guide To Text Blocks > ????https://cr.openjdk.java.net/~jlaskey/Strings/TextBlocksGuide_v9.html > > I will quibble here with Brian's intimation that these documents are > not authoritative. I would argue that being "from the source" implies > that the documents *are* authoritative. They were written by people > very close to the development of the features themselves, and as such > are in the best position to give informed advice about proper and > improper use, avoidance of pitfalls, recommended practices, and so forth. > > With this in mind, I will state that I do not think the Java Style > Guide belongs in the Developer's Guide. The reason is that the > documents have fundamentally different editorial stances. > > The Developer's Guide is primarily operational: it contains > information about how to do things, where to look, whom to ask, step > by step procedures to follow, tips & tricks for working effectively, > and so forth. It covers a wide range of topic areas. For example, one > tip might be > > ??? To switch branches, use 'git switch' instead of 'git checkout -b'. > > Git experts might reasonably take issue with this advice. However, git > experts might not have any opinion at all on other topics, such as one > that covers the proper usage of the noreg-long label on a JBS issue. > As such, the Developer's Guide benefits from input from many > individuals with a broad range of interests, each contributing bits of > expertise in different areas. > > A style guide is fundamentally different. To be useful, it must be > authoritative -- as mentioned above -- and it also must be highly > cohesive. It needs to have a uniform editorial voice that is adhered > to consistently throughout the document. For example, it might take a > prescriptive vs. a descriptive stance, or it might choose a vocabulary > for recommendations of varying strength ("can", "should", "must", > etc.) and use that throughout the document. As such, a style guide is > not at all amenable to a "crowdsourcing" approach and must be edited > by a handful of individuals. Since the editorial approach for the > style guide material is so different from that of the Developer's > Guide, it follows that the style guide should be a different document. > > Personally I'm agnostic to the exact process for delivering a style > guide. If Mark thinks a JEP is required, then maybe that's the best > way forward. But I could imagine other paths forward that wouldn't use > a JEP. > > I would strongly recommend against making the style guide itself be a > JEP. Today, editing a JEP with more than a page or two of text is > already unwieldy. It's easy to introduce errors inadvertently, and > history tracking is virtually nonexistent. Are you suggesting that we should create a sibling project to the Developer's Guide for the style guide(s), with different rules for engagement? /Magnus > It seems unwise to put JIRA+markdown plugin improvements into the > critical path of delivering a style guide. Doing that might prove fatal. > > s'marks From kim.barrett at oracle.com Wed Jul 1 09:48:27 2020 From: kim.barrett at oracle.com (Kim Barrett) Date: Wed, 1 Jul 2020 05:48:27 -0400 Subject: RFR: Updated section on Code Conventions. In-Reply-To: <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> Message-ID: <4CE09277-422A-43E4-91B3-C4AEEE848A82@oracle.com> > On Jul 1, 2020, at 1:23 AM, Stuart Marks wrote: > A style guide is fundamentally different. To be useful, it must be authoritative -- as mentioned above -- and it also must be highly cohesive. It needs to have a uniform editorial voice that is adhered to consistently throughout the document. For example, it might take a prescriptive vs. a descriptive stance, or it might choose a vocabulary for recommendations of varying strength ("can", "should", "must", etc.) and use that throughout the document. As such, a style guide is not at all amenable to a "crowdsourcing" approach and must be edited by a handful of individuals. Since the editorial approach for the style guide material is so different from that of the Developer's Guide, it follows that the style guide should be a different document. > > Personally I'm agnostic to the exact process for delivering a style guide. If Mark thinks a JEP is required, then maybe that's the best way forward. But I could imagine other paths forward that wouldn't use a JEP. > > I would strongly recommend against making the style guide itself be a JEP. Today, editing a JEP with more than a page or two of text is already unwieldy. It's easy to introduce errors inadvertently, and history tracking is virtually nonexistent. It seems unwise to put JIRA+markdown plugin improvements into the critical path of delivering a style guide. Doing that might prove fatal. As someone with another Style Guide update in the works (for HotSpot), I agree having it *be* a JEP is not desirable. It currently resides in the OpenJDK wiki, but that hasn't served us well. It has been suggested that it should reside in the Developers' Guide (by some of the same people suggesting that for the Java Style Guide). I think that would be okay if it can have its own rules for updates. The current draft proposes update rules, which are also in the C++14 update JEP (JDK-8208089) that is driving the document revision. (Whether those are the right rules remains to be seen, though nobody has objected or suggested something else in the 1.5+ years since that was added to the JEP, or in review of the new draft document.) I've also discussed the possibility of putting it in the jdk/jdk repository, probably in the toplevel doc directory. My preference would be to put it in a repository with decent revision control (unlike either the wiki or JBS). Whether that's the Dev-Guide, jdk/jdk, or some other agreeable place is, I think, of less importance. Having it be in the Dev-Guide (or some similar place) has the benefit of having a web "mirror", unlike jdk/jdk/doc. From mark.reinhold at oracle.com Thu Jul 2 00:11:46 2020 From: mark.reinhold at oracle.com (mark.reinhold at oracle.com) Date: Wed, 01 Jul 2020 17:11:46 -0700 Subject: RFR: Updated section on Code Conventions. In-Reply-To: References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> Message-ID: <20200701171146.311157322@eggemoggin.niobe.net> 2020/6/29 2:21:21 -0700, Andrew Haley : > On 26/06/2020 15:13, Magnus Ihse Bursie wrote: >> >> ... >> >> 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. Yes. More precisely, it risks bypassing any meaningful review beyond the small number of people who maintain the Developers? Guide. No matter how well intentioned those people might be, such an important document should be more stable, and changes to it more tightly controlled, than the Developers? Guide is meant to be. (One way to address that is to make every OpenJDK contributor also be a Developers? Guide maintainer, but that doesn?t scale very well. Many contributors will be interested in changes to code-style guidelines. Few, I suspect, will care to review every other change to the Guide.) >> 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. Agreed. - Mark From mark.reinhold at oracle.com Thu Jul 2 00:13:29 2020 From: mark.reinhold at oracle.com (mark.reinhold at oracle.com) Date: Wed, 01 Jul 2020 17:13:29 -0700 Subject: RFR: Updated section on Code Conventions. In-Reply-To: References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> Message-ID: <20200701171329.100085111@eggemoggin.niobe.net> 2020/6/29 10:45:26 -0700, alex.buckley at oracle.com: > ... > > 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. Precisely. - Mark From mark.reinhold at oracle.com Thu Jul 2 00:15:20 2020 From: mark.reinhold at oracle.com (mark.reinhold at oracle.com) Date: Wed, 01 Jul 2020 17:15:20 -0700 Subject: RFR: Updated section on Code Conventions. In-Reply-To: <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> Message-ID: <20200701171520.898247131@eggemoggin.niobe.net> 2020/6/30 22:23:08 -0700, stuart.marks at oracle.com: > ... > > I will quibble here with Brian's intimation that these documents are not > authoritative. I would argue that being "from the source" implies that the > documents *are* authoritative. They were written by people very close to the > development of the features themselves, and as such are in the best position to > give informed advice about proper and improper use, avoidance of pitfalls, > recommended practices, and so forth. Agreed. > With this in mind, I will state that I do not think the Java Style Guide belongs > in the Developer's Guide. The reason is that the documents have fundamentally > different editorial stances. > > The Developer's Guide is primarily operational: it contains information about > how to do things, where to look, whom to ask, step by step procedures to follow, > tips & tricks for working effectively, and so forth. It covers a wide range of > topic areas. For example, one tip might be > > To switch branches, use 'git switch' instead of 'git checkout -b'. > > Git experts might reasonably take issue with this advice. However, git experts > might not have any opinion at all on other topics, such as one that covers the > proper usage of the noreg-long label on a JBS issue. As such, the Developer's > Guide benefits from input from many individuals with a broad range of interests, > each contributing bits of expertise in different areas. > > A style guide is fundamentally different. To be useful, it must be authoritative > -- as mentioned above -- and it also must be highly cohesive. It needs to have a > uniform editorial voice that is adhered to consistently throughout the document. > For example, it might take a prescriptive vs. a descriptive stance, or it might > choose a vocabulary for recommendations of varying strength ("can", "should", > "must", etc.) and use that throughout the document. As such, a style guide is > not at all amenable to a "crowdsourcing" approach and must be edited by a > handful of individuals. Since the editorial approach for the style guide > material is so different from that of the Developer's Guide, it follows that the > style guide should be a different document. Agreed. Strongly. This brings up a related, and important, question: If we?re going to have an authoritative style guide with a uniform editorial voice, then who will sign up to be the editor? Andreas?s draft may be a reasonable starting point, but since he hasn?t been an active OpenJDK contributor for some years now I don?t imagine that he can commit to such a role. Not only would we need an editor to spend time on this, and maintain it for the long haul, but it would inevitably require some of the limited time of at least some of our most experienced contributors. Is that the best use of their time? > Personally I'm agnostic to the exact process for delivering a style guide. If > Mark thinks a JEP is required, then maybe that's the best way forward. But I > could imagine other paths forward that wouldn't use a JEP. > > I would strongly recommend against making the style guide itself be a JEP. > Today, editing a JEP with more than a page or two of text is already unwieldy. > It's easy to introduce errors inadvertently, and history tracking is virtually > nonexistent. It seems unwise to put JIRA+markdown plugin improvements into the > critical path of delivering a style guide. Doing that might prove fatal. Indeed, that would be most unwise. Fortunately, it?s not difficult to address this problem. The job that publishes https://openjdk.java.net/jeps could easily pull the text of select JEPs from any repo that we want, rather than use the bodies of the corresponding JBS issues. We could repurpose the existing jep/jeps repo for that purpose, or (more likely) just set up a new one on GitHub. - Mark From stuart.marks at oracle.com Thu Jul 2 03:54:02 2020 From: stuart.marks at oracle.com (Stuart Marks) Date: Wed, 1 Jul 2020 20:54:02 -0700 Subject: RFR: Updated section on Code Conventions. In-Reply-To: References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> Message-ID: <1fb7cf56-8eb5-b73f-8fd2-8a5f852af40a@oracle.com> On 7/1/20 1:44 AM, Magnus Ihse Bursie wrote: >> A style guide is fundamentally different. To be useful, it must be >> authoritative -- as mentioned above -- and it also must be highly cohesive. It >> needs to have a uniform editorial voice that is adhered to consistently >> throughout the document. For example, it might take a prescriptive vs. a >> descriptive stance, or it might choose a vocabulary for recommendations of >> varying strength ("can", "should", "must", etc.) and use that throughout the >> document. As such, a style guide is not at all amenable to a "crowdsourcing" >> approach and must be edited by a handful of individuals. Since the editorial >> approach for the style guide material is so different from that of the >> Developer's Guide, it follows that the style guide should be a different >> document. >> >> Personally I'm agnostic to the exact process for delivering a style guide. If >> Mark thinks a JEP is required, then maybe that's the best way forward. But I >> could imagine other paths forward that wouldn't use a JEP. >> >> I would strongly recommend against making the style guide itself be a JEP. >> Today, editing a JEP with more than a page or two of text is already unwieldy. >> It's easy to introduce errors inadvertently, and history tracking is virtually >> nonexistent. > Are you suggesting that we should create a sibling project to the Developer's > Guide for the style guide(s), with different rules for engagement? I'm mainly suggesting that the Style Guide not be a chapter plopped into the middle of the Developer's Guide. They seem like fundamentally different documents and so should be treated differently. That said, where would the Style Guide reside? It could be in a separate OpenJDK Project, though that seems like kind of high overhead for a single document. A Project would have separate Reviewers/Committers/Authors, which also seems like high overhead, but maybe something like that is necessary. Or maybe it could be a Group. For example, recently formed groups like the CSR group and the Vulnerability group have their own, special rules of engagement. Or, the Style Guide could be hosted in the Developer's Guide *Project* but still be a different document, with different norms around who is responsible for modifying and reviewing changes. If the Style Guide has a single editor, or a small editorial board who are responsible for updating it, and everybody understands this, that might work just fine. This works for code. For example, I'm a libraries guy, so I don't go mucking around in Hotspot without talking to Hotspot folks about it first. s'marks From LANCE.ANDERSEN at ORACLE.COM Thu Jul 2 12:06:22 2020 From: LANCE.ANDERSEN at ORACLE.COM (Lance Andersen) Date: Thu, 2 Jul 2020 08:06:22 -0400 Subject: RFR: Updated section on Code Conventions. In-Reply-To: <1fb7cf56-8eb5-b73f-8fd2-8a5f852af40a@oracle.com> References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> <1fb7cf56-8eb5-b73f-8fd2-8a5f852af40a@oracle.com> Message-ID: <4A71B635-C45D-4F95-92A1-33F810CFA8F6@ORACLE.COM> > On Jul 1, 2020, at 11:54 PM, Stuart Marks wrote: > > On 7/1/20 1:44 AM, Magnus Ihse Bursie wrote: >>> A style guide is fundamentally different. To be useful, it must be authoritative -- as mentioned above -- and it also must be highly cohesive. It needs to have a uniform editorial voice that is adhered to consistently throughout the document. For example, it might take a prescriptive vs. a descriptive stance, or it might choose a vocabulary for recommendations of varying strength ("can", "should", "must", etc.) and use that throughout the document. As such, a style guide is not at all amenable to a "crowdsourcing" approach and must be edited by a handful of individuals. Since the editorial approach for the style guide material is so different from that of the Developer's Guide, it follows that the style guide should be a different document. >>> >>> Personally I'm agnostic to the exact process for delivering a style guide. If Mark thinks a JEP is required, then maybe that's the best way forward. But I could imagine other paths forward that wouldn't use a JEP. >>> >>> I would strongly recommend against making the style guide itself be a JEP. Today, editing a JEP with more than a page or two of text is already unwieldy. It's easy to introduce errors inadvertently, and history tracking is virtually nonexistent. >> Are you suggesting that we should create a sibling project to the Developer's Guide for the style guide(s), with different rules for engagement? > > I'm mainly suggesting that the Style Guide not be a chapter plopped into the middle of the Developer's Guide. They seem like fundamentally different documents and so should be treated differently. > +1 > That said, where would the Style Guide reside? It could be in a separate OpenJDK Project, though that seems like kind of high overhead for a single document. A Project would have separate Reviewers/Committers/Authors, which also seems like high overhead, but maybe something like that is necessary. Or maybe it could be a Group. For example, recently formed groups like the CSR group and the Vulnerability group have their own, special rules of engagement. > > Or, the Style Guide could be hosted in the Developer's Guide *Project* but still be a different document, with different norms around who is responsible for modifying and reviewing changes. How about we keep this simple to start and keep this as an additional document in the Developer Guide Project. If we find the need to place it in its own project later, then we can. I think it is more important to move forward with the updates to the style guide now that we have some momentum behind doing so. > If the Style Guide has a single editor, or a small editorial board who are responsible for updating it, and everybody understands this, that might work just fine. +1 > This works for code. For example, I'm a libraries guy, so I don't go mucking around in Hotspot without talking to Hotspot folks about it first. > +1 > s'marks Best Lance ------------------ Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037 Oracle Java Engineering 1 Network Drive Burlington, MA 01803 Lance.Andersen at oracle.com From jesper.wilhelmsson at oracle.com Thu Jul 2 17:47:52 2020 From: jesper.wilhelmsson at oracle.com (Jesper Wilhelmsson) Date: Thu, 2 Jul 2020 19:47:52 +0200 Subject: RFR: Updated section on Code Conventions. In-Reply-To: <4A71B635-C45D-4F95-92A1-33F810CFA8F6@ORACLE.COM> References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> <1fb7cf56-8eb5-b73f-8fd2-8a5f852af40a@oracle.com> <4A71B635-C45D-4F95-92A1-33F810CFA8F6@ORACLE.COM> Message-ID: I'll make an attempt at summarizing this discussion so far. There are a few issues that seems to be key to decide where a Style Guide can be located, all of them have pros and cons. The list below is not sorted in any way. 1) Version control + Any git/mercurial based solution will work here. + Even the OpenJDK wiki that was briefly mentioned have adequate change history. - A traditional JBS-based JEP will not work. 2) Small, controlled, set of editors + A JEP has a natural small set of authors and editors. Even though it's not explicitly written anywhere that people shouldn't edit random JEPs I haven't seen a lot of random edits on other people's JEPs. It would be good to explicitly clarify that JEPs are not to be edited without talking to the Author first, but that's a general JEP thing and is unrelated to this discussion. + A separate project or a Group maintaining its own document would also achieve this. + Having a separate document in the Developers' Guide project can also achieve this. We already have examples of different files/areas in the same Project and source tree (in the JDK) with different rules for reviews and different sets of authors. The same holds true for having the Style Guide reside in the JDK repository. - A wiki page will not satisfy this. 3) Make it obvious that this is an OpenJDK style guide + A JEP will provide enough "frame" around the Style Guide to make it obvious that this is intended for OpenJDK. + Any solution where the Style Guide is a separate document can achieve this as you can decorate the guide with any desired wording to make it scream OpenJDK in the same way as a JEP would do. + Having the Style Guide as an inlined chapter in the Developers' Guide will achieve this, but it has never been my intention to inline the Style Guide within the Developers' Guide even if that guide may be merged into a single page. I don't think this is a good idea and it won't happen. 4) Make sure changes are broadly reviewed - No solution discussed so far will achieve this. Changes in JEPs are usually not reviewed at all. Changes in a separate repository (special JEP, Developers' Guide, or other repo) are only reviewed by those who follow that repo. The only way to get a wide audience to look at changes would be to send them to jdk-dev, and this would have to be explicitly stated in some change guide for the Style Guide regardless of where it is published. The exception may be if the Style Guide is located in the JDK source repo, then it could be standard procedure to send changes for review on jdk-dev. It seems to me that there are several options that fulfills three out of four requirements, and in order to meet the last one a separate paragraph with a set of rules for updates would be required regardless of where and how the Style Guide is published. Such a paragraph could easily define who is allowed to edit and how reviews should happen. I personally don't have a strong opinion on where to place the Style Guide other than what I've said before; If it's supposed to be rules rather than guidelines then a JEP is a good place, if these are guidelines I would personally not vote for a JEP. Several experienced voices has expressed what I interpret as "these are rules regardless of what we call them", and I have no evidence to support any other opinion. As a side note I just want to point out that we are currently three Reviewers in the Developers' Guide Project, none who is likely to accept changes to the Style Guide without following the proper protocol. So I can pretty much guarantee that no random updates will happen if the Style Guide would be placed there. There is some more work to do before the same claim can be made for a JEP. /Jesper > On 2 Jul 2020, at 14:06, Lance Andersen wrote: >> On Jul 1, 2020, at 11:54 PM, Stuart Marks > wrote: >> On 7/1/20 1:44 AM, Magnus Ihse Bursie wrote: >>>> A style guide is fundamentally different. To be useful, it must be authoritative -- as mentioned above -- and it also must be highly cohesive. It needs to have a uniform editorial voice that is adhered to consistently throughout the document. For example, it might take a prescriptive vs. a descriptive stance, or it might choose a vocabulary for recommendations of varying strength ("can", "should", "must", etc.) and use that throughout the document. As such, a style guide is not at all amenable to a "crowdsourcing" approach and must be edited by a handful of individuals. Since the editorial approach for the style guide material is so different from that of the Developer's Guide, it follows that the style guide should be a different document. >>>> >>>> Personally I'm agnostic to the exact process for delivering a style guide. If Mark thinks a JEP is required, then maybe that's the best way forward. But I could imagine other paths forward that wouldn't use a JEP. >>>> >>>> I would strongly recommend against making the style guide itself be a JEP. Today, editing a JEP with more than a page or two of text is already unwieldy. It's easy to introduce errors inadvertently, and history tracking is virtually nonexistent. >>> Are you suggesting that we should create a sibling project to the Developer's Guide for the style guide(s), with different rules for engagement? >> >> I'm mainly suggesting that the Style Guide not be a chapter plopped into the middle of the Developer's Guide. They seem like fundamentally different documents and so should be treated differently. >> > > +1 > >> That said, where would the Style Guide reside? It could be in a separate OpenJDK Project, though that seems like kind of high overhead for a single document. A Project would have separate Reviewers/Committers/Authors, which also seems like high overhead, but maybe something like that is necessary. Or maybe it could be a Group. For example, recently formed groups like the CSR group and the Vulnerability group have their own, special rules of engagement. >> >> Or, the Style Guide could be hosted in the Developer's Guide *Project* but still be a different document, with different norms around who is responsible for modifying and reviewing changes. > > How about we keep this simple to start and keep this as an additional document in the Developer Guide Project. If we find the need to place it in its own project later, then we can. > > I think it is more important to move forward with the updates to the style guide now that we have some momentum behind doing so. > >> If the Style Guide has a single editor, or a small editorial board who are responsible for updating it, and everybody understands this, that might work just fine. > > +1 > >> This works for code. For example, I'm a libraries guy, so I don't go mucking around in Hotspot without talking to Hotspot folks about it first. >> > +1 > > >> s'marks > > > Best > Lance > ------------------ > > > > > Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037 > Oracle Java Engineering > 1 Network Drive > Burlington, MA 01803 > Lance.Andersen at oracle.com From stuart.marks at oracle.com Thu Jul 2 21:56:10 2020 From: stuart.marks at oracle.com (Stuart Marks) Date: Thu, 2 Jul 2020 14:56:10 -0700 Subject: RFR: Updated section on Code Conventions. In-Reply-To: <4b7d416c-826b-ee79-7623-6e89c8e2ac5c@oracle.com> References: <20200622094020.797147833@eggemoggin.niobe.net> <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com> <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com> <1fb7cf56-8eb5-b73f-8fd2-8a5f852af40a@oracle.com> <4A71B635-C45D-4F95-92A1-33F810CFA8F6@ORACLE.COM> <4b7d416c-826b-ee79-7623-6e89c8e2ac5c@oracle.com> Message-ID: On 7/2/20 6:40 AM, Magnus Ihse Bursie wrote: > I thought, or at least hoped (perhaps naively), that we had, as an > organization, finally learned that being a bit more agile -- without > compromising on our high standard of quality -- had done wonders for our > project. That 6-month releases was a boon sine qua non. That doing things > mostly right, releasing them, and then adjusting them based on feedback, was > vastly superior to doing nothing in fear of not doing it perfect from the start. > > But this view collides heavily with Mark's that we, before we even start > considering what a Style Guide should contain, must have one of our most > experienced developers signing up to be the sole editor for a substantial > period of time. With that premise, we can be quite sure that we will never get > a Style Guide. If this is indeed the expected and preferred outcome for the > proponents of this line, I think it borders on dishonesty: if so, please say > that you do not *want* a style guide for OpenJDK. And if you do want a style > guide, can you with a straight face say that it is likely that we will ever > get one with that kind of requirements? We have waited for years, and years > for that kind of perfection, but with nothing to show. What will be different > in the coming five years? Well there's rather a lot to unpack here. It's certainly been frustrating that the 2o-year-old /Code Conventions/ hasn't been updated. Andreas Lundblad made a credible attempt to do so, now five years ago, and I don't know why that stalled out. (Nor do I want to relitigate the issues that led to the effort stalling out.) It seems like adding the style guide to the Developer's Guide offers a path forward. Doing that allows everybody to work on it. We can make quick progress on it after that, right? This is surely better than what we have now (nothing), because the best is the enemy of the good, right? In my estimation, doing this will lead to a "crowdsourcing" of the effort, and this will leave us in a /worse/ position than we're in today. (Believe it or not.) As an example of where crowdsourcing fails, I'll point to Stack Overflow Documentation. [1] (Not Stack Overflow the main Q&A site, which seems reasonably successful as a crowdsourced Q&A site.) Stack Overflow Documentation [2] was an effort to crowdsource fixing the "documentation problem." Documentation does seem to be a general problem in the industry, and certainly Java has its share of documentation problems. Stack Overflow Documentation was launched and then shut down perhaps a year later; the explanation is given in [3]. That explanation offers mostly a business rationale for shutting it down: lack of growth in number of users, inability to generate revenue for Stack Overflow the company, and so forth. Quite reasonable. But little has been said about the /quality/ of documentation produced by the Stack Overflow Documentation project. The SO Documentation materials are all CC BY-SA. The company made an archive of that data available, and it's been re-hosted elsewhere so that it's possible to look at it. For example, take a look at the Collections topic of the Java documentation category. [4] I spent a few minutes with it, and *frankly, it is just terrible.* It was this way when the SO Documentation project was active. Back then I had looked at it for about five minutes, and I quickly decided that it was *beyond repair*. There are so many problems, it's hard to know where to start. Fundamentally I think the choice of topics is bad and they are organized poorly. Apparently no thought was given to what topics are important or what order to cover them in. It's not even clear what audience the material is intended for. (These issues are certainly related.) It's random train-of-thought as far as I can tell. It suffers from an utter lack of cohesion. Stack Overflow Documentation is this way /because/ it's a crowdsourced effort. Surely the Style Guide couldn't get this bad. After all, we'll use Andreas Lundblad's draft as a starting point. It seems to be pretty cohesive already, so it wouldn't get as bad as SO Documentation, right? Well I'm not confident about that. It takes positive effort to keep something in good shape. In the absence of a central editor, a few small changes here and there by a few different individuals will quickly give rise to internal contradictions and other inconsistencies. These will soon damage the credibility of the entire document. You know how quickly bit-rot sets in when software isn't maintained? Well, it's the same way with documents. ** Where does that leave us? I agree with the desire to move forward quickly. I don't think Mark's (or my) approach of having a central editorial authority necessarily implies slow progress. However, people who are willing and able to do that are in short supply, and finding those people could take (and has taken) a long time. I see the temptation to just check it in and let people work on it. It seems like that would allow for lots of progress. But that's a mirage. It will just lead to chaos and disorganization and it will eventually end up being a waste of everybody's time. s'marks [1] https://stackoverflow.com/documentation [2] https://meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-proposed-expansion-of-stack-overflow [3] https://meta.stackoverflow.com/questions/354217/sunsetting-documentation [4] https://riptutorial.com/java/topic/90/collections From jwilhelm at openjdk.java.net Thu Jul 2 23:30:37 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Thu, 2 Jul 2020 23:30:37 GMT Subject: RFR: Filing bug, ProblemListing, Backing out Message-ID: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Filing bug, ProblemListing, Backing out ------------- Commit messages: - Filing bug, ProblemListing, Backing out Changes: https://git.openjdk.java.net/guide/pull/21/files Webrev: https://webrevs.openjdk.java.net/guide/21/webrev.00 Stats: 162 lines in 2 files changed: 162 ins; 0 del; 0 mod Patch: https://git.openjdk.java.net/guide/pull/21.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/21/head:pull/21 PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Thu Jul 2 23:33:16 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Thu, 2 Jul 2020 23:33:16 GMT Subject: RFR: Filing bug, ProblemListing, Backing out In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Thu, 2 Jul 2020 23:14:50 GMT, Jesper Wilhelmsson wrote: > Filing bug, ProblemListing, Backing out src/next.md line 26: > 25: * Before filing a bug, verify that there isn't already a bug filed for this issue. > 26: * Add relevant labels like `intermittent`, `regression`, `testbug` etc. > 27: * Set affects version to the JDK version(s) where the failure was seen. didn't we _deprecate_ `testbug` label and decided to use `noreg-self` to mark all test bugs? ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Thu Jul 2 23:35:44 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Thu, 2 Jul 2020 23:35:44 GMT Subject: RFR: Filing bug, ProblemListing, Backing out In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: <9qhHh9a0zdEHRrvVL_DgphJCymLQ4K6RWBLbty6eWGY=.80000ce1-174f-4e3f-80a6-5fa25a9e256f@github.com> On Thu, 2 Jul 2020 23:14:50 GMT, Jesper Wilhelmsson wrote: > Filing bug, ProblemListing, Backing out src/next.md line 69: > 68: ~~~ > 69: sun.tools.jcmd.MyTest.java 4711 windows-all > 70: ~~~ this actually should be filename: Suggestion: sun/tools/jcmd/MyTest.java 4711 windows-all ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Thu Jul 2 23:38:25 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Thu, 2 Jul 2020 23:38:25 GMT Subject: RFR: Filing bug, ProblemListing, Backing out In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Thu, 2 Jul 2020 23:14:50 GMT, Jesper Wilhelmsson wrote: > Filing bug, ProblemListing, Backing out src/index.md line 30: > 29: * [Filing a Bug](next.html#filing-a-bug) > 30: * [ProblemListing or Ignoring a test](next.html#problemlisting-or-ignore-ing-a-test) > 31: * [Backing Out a Change](next.html#backing-out-a-change) shouldn't it use the exact same words as the section's title? Suggestion: * [ProblemListing or `@ignore`-ing a Test](next.html#problemlisting-or-ignore-ing-a-test) ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Thu Jul 2 23:40:40 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Thu, 2 Jul 2020 23:40:40 GMT Subject: RFR: Filing bug, ProblemListing, Backing out In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Thu, 2 Jul 2020 23:14:50 GMT, Jesper Wilhelmsson wrote: > Filing bug, ProblemListing, Backing out Hi Jesper, modulo a few comments, ProblemListing part looks good. thank you again for writing this. ------------- Changes requested by iignatyev (no project role). PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Thu Jul 2 23:49:37 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Thu, 2 Jul 2020 23:49:37 GMT Subject: RFR: Filing bug, ProblemListing, Backing out In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Thu, 2 Jul 2020 23:30:54 GMT, Igor Ignatyev wrote: >> Filing bug, ProblemListing, Backing out > > src/next.md line 26: > >> 25: * Before filing a bug, verify that there isn't already a bug filed for this issue. >> 26: * Add relevant labels like `intermittent`, `regression`, `testbug` etc. >> 27: * Set affects version to the JDK version(s) where the failure was seen. > > didn't we _deprecate_ `testbug` label and decided to use `noreg-self` to mark all test bugs? Yes we did. You're absolutely right. Will change that. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Thu Jul 2 23:53:12 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Thu, 2 Jul 2020 23:53:12 GMT Subject: RFR: Filing bug, ProblemListing, Backing out In-Reply-To: <9qhHh9a0zdEHRrvVL_DgphJCymLQ4K6RWBLbty6eWGY=.80000ce1-174f-4e3f-80a6-5fa25a9e256f@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <9qhHh9a0zdEHRrvVL_DgphJCymLQ4K6RWBLbty6eWGY=.80000ce1-174f-4e3f-80a6-5fa25a9e256f@github.com> Message-ID: On Thu, 2 Jul 2020 23:33:40 GMT, Igor Ignatyev wrote: >> Filing bug, ProblemListing, Backing out > > src/next.md line 69: > >> 68: ~~~ >> 69: sun.tools.jcmd.MyTest.java 4711 windows-all >> 70: ~~~ > > this actually should be filename: > Suggestion: > > sun/tools/jcmd/MyTest.java 4711 windows-all Right. Will fix. > src/index.md line 30: > >> 29: * [Filing a Bug](next.html#filing-a-bug) >> 30: * [ProblemListing or Ignoring a test](next.html#problemlisting-or-ignore-ing-a-test) >> 31: * [Backing Out a Change](next.html#backing-out-a-change) > > shouldn't it use the exact same words as the section's title? > Suggestion: > > * [ProblemListing or `@ignore`-ing a Test](next.html#problemlisting-or-ignore-ing-a-test) Good catch! ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Fri Jul 3 00:27:31 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Fri, 3 Jul 2020 00:27:31 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: <5qtXXfsLLGCsPljHNgJHvdo9Ulq3QKij-a8In1EJctI=.6931b7e5-71a5-4f36-b529-bf58304996b5@github.com> On Fri, 3 Jul 2020 00:27:23 GMT, Jesper Wilhelmsson wrote: >> Filing bug, ProblemListing, Backing out > > Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: > > Fixed comments from review src/next.md line 90: > 89: > 90: #### ProblemListing some, but not all, test cases in a file > 91: actually, due to [CODETOOLS-7902712](https://bugs.openjdk.java.net/browse/CODETOOLS-7902712), you can't use `foo/bar/MyTest.java` entry to exclude all test cases, you have to list all of them explicitly. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Fri Jul 3 00:27:30 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 3 Jul 2020 00:27:30 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Thu, 2 Jul 2020 23:38:27 GMT, Igor Ignatyev wrote: >> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: >> >> Fixed comments from review > > Hi Jesper, > > modulo a few comments, ProblemListing part looks good. thank you again for writing this. Thank you Igor! All comments fixed and I also added the example for ProblemListing single test cases that you sent. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Fri Jul 3 00:27:23 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Fri, 3 Jul 2020 00:27:23 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: > Filing bug, ProblemListing, Backing out Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: Fixed comments from review ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/21/files - new: https://git.openjdk.java.net/guide/pull/21/files/0592b2e0..3147007c Webrevs: - full: https://webrevs.openjdk.java.net/guide/21/webrev.01 - incr: https://webrevs.openjdk.java.net/guide/21/webrev.00-01 Stats: 28 lines in 2 files changed: 21 ins; 0 del; 7 mod Patch: https://git.openjdk.java.net/guide/pull/21.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/21/head:pull/21 PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 21:16:01 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 21:16:01 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v3] In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: > Filing bug, ProblemListing, Backing out Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: Added comment about CODETOOLS-7902712 ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/21/files - new: https://git.openjdk.java.net/guide/pull/21/files/3147007c..6bd69e06 Webrevs: - full: https://webrevs.openjdk.java.net/guide/21/webrev.02 - incr: https://webrevs.openjdk.java.net/guide/21/webrev.01-02 Stats: 2 lines in 1 file changed: 2 ins; 0 del; 0 mod Patch: https://git.openjdk.java.net/guide/pull/21.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/21/head:pull/21 PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 21:16:02 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 21:16:02 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <5qtXXfsLLGCsPljHNgJHvdo9Ulq3QKij-a8In1EJctI=.6931b7e5-71a5-4f36-b529-bf58304996b5@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <5qtXXfsLLGCsPljHNgJHvdo9Ulq3QKij-a8In1EJctI=.6931b7e5-71a5-4f36-b529-bf58304996b5@github.com> Message-ID: On Fri, 3 Jul 2020 00:17:10 GMT, Igor Ignatyev wrote: >> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: >> >> Fixed comments from review > > src/next.md line 90: > >> 89: >> 90: #### ProblemListing some, but not all, test cases in a file >> 91: > > actually, due to [CODETOOLS-7902712](https://bugs.openjdk.java.net/browse/CODETOOLS-7902712), you can't use > `foo/bar/MyTest.java` entry to exclude all test cases, you have to list all of them explicitly. Thanks for catching that! I've added a comment about this. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 21:16:17 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 21:16:17 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Mon, 6 Jul 2020 19:08:20 GMT, Phil Race wrote: >> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: >> >> Fixed comments from review > > src/next.md line 22: > >> 21: When a new failure is found in the JDK a bug should be filed to describe and track the issue. Depending on your >> role in the OpenJDK you can either use the [Bug Report Tool](https://bugreport.java.com/) or, if you are Author in an >> OpenJDK Project, report the bug directly in the [JDK Bug System](https://bugs.openjdk.java.net/). Try to make the bug >> report as complete as possible to make it easier to triage and investigate the bug. It's not the reporter's >> responsibility to set a correct priority, but a good guess is always better than a default value. To help with setting >> the right priority consider things like how the bug impacts the product and our testing, how likely is it that the bug >> triggers, and how difficult is it to work around the bug if it's not fixed soon. 22: 23: A few things to keep in mind >> when filing a new bug: > > and whether it is a recent regression, since that may break existing applications. regressions are often higher > priority than long standing bugs. Added this to the text. > src/next.md line 42: > >> 41: Sometimes tests break. It could be due to bugs in the test itself, or due to changed functionality in the code that >> the test is testing. While working on a fix, it can be useful to stop the test from being executed in everyone else's >> testing to reduce noise, especially if the test is expected to fail for more than a day. There are two ways to stop a >> test from being run in standard test runs: ProblemListing and using the `@ignore` keyword. Removing tests isn't the >> standard way to remove a failure. A failing test is expected to be a regression and should ideally be handled promptly >> with high urgency. 42: 43: I'll say it right away so that it's not forgotten at the end: Remember to remove the JBS id >> from the ProblemList or the test when the bug is closed. This is especially easy to forget if a bug is closed as a >> duplicate or 'Will Not Fix'. > > this isn't the whole picture A test may fail because it is now being tested in new environment, (eg new platform or > platform release) not just because of the afore stated reasons. This would not be a regression but might still be > important. Agreed. I have updated the text to reflect this. > src/next.md line 48: > >> 47: ProblemListing is used for a short term exclusion while a test is being fixed, and for the exclusion of >> intermittently failing tests that cause too much noise, but can still be useful to run on an ad-hoc basis. >> ProblemListing is done in the file `ProblemList.txt`. There are actually several ProblemList files to choose from. >> Their location and name hint about what area or feature each file belongs to. Each file has sections for different >> components. All ProblemList files complement each other to build the total set of tests to exclude in JTReg runs. 48: >> 49: ~~~ > > the emphasis that the exclusion is short lived is sadly unduly optimistic. Problem listing can be used for long term > exclusions too. It is still better than deleting a valid test. "is" -> "should be" ? ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 21:38:17 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 21:38:17 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: <-ZVLtI8_fHzSX9ja4CjSyUtZI9raZfGys-dj22sbPec=.e109e4fb-0d8f-4321-a7e0-a9e1bb2713cb@github.com> On Mon, 6 Jul 2020 20:00:12 GMT, Phil Race wrote: >> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: >> >> Fixed comments from review > > src/next.md line 73: > >> 72: In this example, `MyTest.java` is ProblemListed on windows, tracked by bug `JDK-4711`. >> 73: >> 74: Currently there's [no support for multiple lines for the same >> test](https://bugs.openjdk.java.net/browse/CODETOOLS-7902481). For this reason it's important to always make sure >> there's no existing entry for the test before adding a new one, as multiple entries might lead to unexpected results, >> e.g. > > Not sure where in this review to insert this but there is a sensible policy that you should make sure the bug report is > open. If you are submitting it that is easy to ensure but there have been cases where bugs are closed (without > necessarily being fixed) and the issue remains PL'd. A legitimate case where this occurs if a bug is fixed in one line > of development but the fix is not (yet:?) backported and I'm not sure how the "sensible policy" accounts for that. This is a very good point. I'm not sure how to express it though since this is meant to be a document for everyone, not only Oracle developers. I'm not sure what you mean with regards to the backport. If a fix is made in mainline it's removed from the ProblemList in mainline. The backport should remove it from the ProblemList in the update release once it's pushed there. The one thing that could be problematic is the `problemlist` label since that is only supposed to be on the main bug. But on the other hand I don't think there is any automation that looks at the ProblemLists in the update trains so having the label tied to the mainline issue won't be a problem in practice I think. > src/next.md line 147: > >> 146: >> 147: If a change cause a regression that can't be fixed within reasonable time the best way to handle the regression >> can be to back out the change. Backing out means that the inverse (anti-delta) of the change is pushed to effectively >> undo the change in the repository. There are two parts to this task, how to do the bookkeeping in JBS, and how to do >> the actual backout in mercurial. 148: > > cause -> causes Fixed. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 21:46:26 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 21:46:26 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: <5tAe6Ivdkicr5HUMqXo4JJvPeN_chYNXx009PPUjOTo=.c093fac7-ce49-4d98-aced-fc0c28403996@github.com> On Mon, 6 Jul 2020 20:04:26 GMT, Phil Race wrote: >> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: >> >> Fixed comments from review > > src/next.md line 149: > >> 148: >> 149: The backout is a regular change and will have to go through the standard code review process, but is considered a >> trivial change and thus it requires only one Reviewer and will avoid the 24h code review window, even for areas where >> stricter rules usually applies. The rationale is that a backout is usually urgent in nature and the change itself is >> automatically created by hg, and reviewed by the person who is performing the backout, so even though only one >> additional Reviewer is required the change will in practice get two reviews. 150: > > where is the 24h code review window discussed ? > It might be a sensible policy for non-urgent fixes but I've never seen it documented/codified and we've never had it as > a rule in the client area. That text hasn't been written yet. The 24h-rule is in use in the VM. I don't know if any other area use this rule. It doesn't apply to urgent fixes. Once we write that text it should specify if there are differences between areas. Whether it's needed or not depends, I guess, on how distributed the active area developers are over timezones. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Mon Jul 6 22:08:31 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Mon, 6 Jul 2020 22:08:31 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <-ZVLtI8_fHzSX9ja4CjSyUtZI9raZfGys-dj22sbPec=.e109e4fb-0d8f-4321-a7e0-a9e1bb2713cb@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <-ZVLtI8_fHzSX9ja4CjSyUtZI9raZfGys-dj22sbPec=.e109e4fb-0d8f-4321-a7e0-a9e1bb2713cb@github.com> Message-ID: On Mon, 6 Jul 2020 21:34:56 GMT, Jesper Wilhelmsson wrote: >> src/next.md line 73: >> >>> 72: In this example, `MyTest.java` is ProblemListed on windows, tracked by bug `JDK-4711`. >>> 73: >>> 74: Currently there's [no support for multiple lines for the same >>> test](https://bugs.openjdk.java.net/browse/CODETOOLS-7902481). For this reason it's important to always make sure >>> there's no existing entry for the test before adding a new one, as multiple entries might lead to unexpected results, >>> e.g. >> >> Not sure where in this review to insert this but there is a sensible policy that you should make sure the bug report is >> open. If you are submitting it that is easy to ensure but there have been cases where bugs are closed (without >> necessarily being fixed) and the issue remains PL'd. A legitimate case where this occurs if a bug is fixed in one line >> of development but the fix is not (yet:?) backported and I'm not sure how the "sensible policy" accounts for that. > > This is a very good point. I'm not sure how to express it though since this is meant to be a document for everyone, not > only Oracle developers. > I'm not sure what you mean with regards to the backport. If a fix is made in mainline it's removed from the ProblemList > in mainline. The backport should remove it from the ProblemList in the update release once it's pushed there. The one > thing that could be problematic is the `problemlist` label since that is only supposed to be on the main bug. But on > the other hand I don't think there is any automation that looks at the ProblemLists in the update trains so having the > label tied to the mainline issue won't be a problem in practice I think. I think Phil is talking about a separate line of development of current feature release, i.e. `jdk/jdk` vs `jdk/client`, and not about `jdk/jdk` vs `11u`. let's say you have fixed `JDK-4711` in `jdk/client` repo, but your fix hasn't been propagated to `jdk/jdk` yet, and folks in `jdk/jdk` are still affected by `JDK-4711` and see test failures (from non-problem-listed tests), so they want to go and problem-list them, but JBS says that `JDK-4711` is already closed. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Mon Jul 6 22:11:35 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Mon, 6 Jul 2020 22:11:35 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <5tAe6Ivdkicr5HUMqXo4JJvPeN_chYNXx009PPUjOTo=.c093fac7-ce49-4d98-aced-fc0c28403996@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <5tAe6Ivdkicr5HUMqXo4JJvPeN_chYNXx009PPUjOTo=.c093fac7-ce49-4d98-aced-fc0c28403996@github.com> Message-ID: On Mon, 6 Jul 2020 21:44:09 GMT, Jesper Wilhelmsson wrote: >> src/next.md line 149: >> >>> 148: >>> 149: The backout is a regular change and will have to go through the standard code review process, but is considered a >>> trivial change and thus it requires only one Reviewer and will avoid the 24h code review window, even for areas where >>> stricter rules usually applies. The rationale is that a backout is usually urgent in nature and the change itself is >>> automatically created by hg, and reviewed by the person who is performing the backout, so even though only one >>> additional Reviewer is required the change will in practice get two reviews. 150: >> >> where is the 24h code review window discussed ? >> It might be a sensible policy for non-urgent fixes but I've never seen it documented/codified and we've never had it as >> a rule in the client area. > > That text hasn't been written yet. The 24h-rule is in use in the VM. I don't know if any other area use this rule. It > doesn't apply to urgent fixes. Once we write that text it should specify if there are differences between areas. > Whether it's needed or not depends, I guess, on how distributed the active area developers are over timezones. given 24h rule is VM-specific, I think it might be reasonable to omit in this text and just say that backouts are considered trivial changes, and have the difference in rules for trivial and non-trivial changes described in yet-not-written reviewing doc (or its VM part) ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 22:28:50 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 22:28:50 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Mon, 6 Jul 2020 20:09:30 GMT, Phil Race wrote: >> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: >> >> Fixed comments from review > > src/next.md line 154: > >> 153: #. Close the original JBS issue **(O)**. >> 154: * "Verify" the issue and choose "Fix Failed". >> 155: #. If the intention is to fix the change and submit it again, create a redo-issue **(R)** to track that the work >> still needs to be done. > > I have strong objections to fix failed ever being used and oppose it being recommended here. Unless the fixer and their > reviewers completely failed at their job what you usually have is some other problem caused by the fix and the fix > actually succeeded. I guess this is a question for those who normally handle fix verification and may have scripts that look for different verifications. There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs verification. So changing to using this would probably cause problems. That leaves "Fix failed". Maybe Joe knows why this was designed as it is? Anyhow, it is the current process and we need to bring it up with the right people before changing it. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iignatyev at openjdk.java.net Mon Jul 6 22:36:12 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Mon, 6 Jul 2020 22:36:12 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Mon, 6 Jul 2020 22:25:58 GMT, Jesper Wilhelmsson wrote: >> src/next.md line 154: >> >>> 153: #. Close the original JBS issue **(O)**. >>> 154: * "Verify" the issue and choose "Fix Failed". >>> 155: #. If the intention is to fix the change and submit it again, create a redo-issue **(R)** to track that the work >>> still needs to be done. >> >> I have strong objections to fix failed ever being used and oppose it being recommended here. Unless the fixer and their >> reviewers completely failed at their job what you usually have is some other problem caused by the fix and the fix >> actually succeeded. > > I guess this is a question for those who normally handle fix verification and may have scripts that look for different > verifications. > There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". > "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not > verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed > out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs > verification. So changing to using this would probably cause problems. That leaves "Fix failed". Maybe Joe knows why > this was designed as it is? Anyhow, it is the current process and we need to bring it up with the right people before > changing it. AFAIK, The verification process isn't part of any OpenJDK process and is used/done mainly internally by Oracle. why do you think that verification status should be set for all backed out issues? ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 22:36:13 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 22:36:13 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <-ZVLtI8_fHzSX9ja4CjSyUtZI9raZfGys-dj22sbPec=.e109e4fb-0d8f-4321-a7e0-a9e1bb2713cb@github.com> Message-ID: <8mJye6cfKeNaz0ew5OdL5EhaG0RFdK1S3FCrCPL8vto=.1539ac1f-38f7-4fa0-b0be-29dca69b1289@github.com> On Mon, 6 Jul 2020 22:05:42 GMT, Igor Ignatyev wrote: >> This is a very good point. I'm not sure how to express it though since this is meant to be a document for everyone, not >> only Oracle developers. >> I'm not sure what you mean with regards to the backport. If a fix is made in mainline it's removed from the ProblemList >> in mainline. The backport should remove it from the ProblemList in the update release once it's pushed there. The one >> thing that could be problematic is the `problemlist` label since that is only supposed to be on the main bug. But on >> the other hand I don't think there is any automation that looks at the ProblemLists in the update trains so having the >> label tied to the mainline issue won't be a problem in practice I think. > > I think Phil is talking about a separate line of development of current feature release, i.e. `jdk/jdk` vs > `jdk/client`, and not about `jdk/jdk` vs `11u`. let's say you have fixed `JDK-4711` in `jdk/client` repo, but your fix > hasn't been propagated to `jdk/jdk` yet, and folks in `jdk/jdk` are still affected by `JDK-4711` and see test failures > (from non-problem-listed tests), so they want to go and problem-list them, but JBS says that `JDK-4711` is already > closed. Ah, of course. There is no implemented solution for that right now. Two fairly easy options would be 1, Merge client into mainline, or 2, use a different fix version for client like done for project repos. This is something that we should bring up in a different thread with a different audience. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From david.holmes at oracle.com Mon Jul 6 22:41:06 2020 From: david.holmes at oracle.com (David Holmes) Date: Tue, 7 Jul 2020 08:41:06 +1000 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> Hi Igor, On 7/07/2020 8:36 am, Igor Ignatyev wrote: > On Mon, 6 Jul 2020 22:25:58 GMT, Jesper Wilhelmsson wrote: > >>> src/next.md line 154: >>> >>>> 153: #. Close the original JBS issue **(O)**. >>>> 154: * "Verify" the issue and choose "Fix Failed". >>>> 155: #. If the intention is to fix the change and submit it again, create a redo-issue **(R)** to track that the work >>>> still needs to be done. >>> >>> I have strong objections to fix failed ever being used and oppose it being recommended here. Unless the fixer and their >>> reviewers completely failed at their job what you usually have is some other problem caused by the fix and the fix >>> actually succeeded. >> >> I guess this is a question for those who normally handle fix verification and may have scripts that look for different >> verifications. >> There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". >> "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not >> verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed >> out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs >> verification. So changing to using this would probably cause problems. That leaves "Fix failed". Maybe Joe knows why >> this was designed as it is? Anyhow, it is the current process and we need to bring it up with the right people before >> changing it. > > AFAIK, The verification process isn't part of any OpenJDK process and is used/done mainly internally by Oracle. why do > you think that verification status should be set for all backed out issues? That was the process that was defined. If a fix has to be backed out then the fix is considered to have "failed". David ----- > ------------- > > PR: https://git.openjdk.java.net/guide/pull/21 > From jwilhelm at openjdk.java.net Mon Jul 6 22:41:25 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 22:41:25 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <5tAe6Ivdkicr5HUMqXo4JJvPeN_chYNXx009PPUjOTo=.c093fac7-ce49-4d98-aced-fc0c28403996@github.com> Message-ID: On Mon, 6 Jul 2020 22:08:39 GMT, Igor Ignatyev wrote: >> That text hasn't been written yet. The 24h-rule is in use in the VM. I don't know if any other area use this rule. It >> doesn't apply to urgent fixes. Once we write that text it should specify if there are differences between areas. >> Whether it's needed or not depends, I guess, on how distributed the active area developers are over timezones. > > given 24h rule is VM-specific, I think it might be reasonable to omit in this text and just say that backouts are > considered trivial changes, and have the difference in rules for trivial and non-trivial changes described in > yet-not-written reviewing doc (or its VM part) Yes, I agree. There is no need to define (again) what trivial means here. The word should be a link to where "trivial" is defined. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Mon Jul 6 22:47:43 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Mon, 6 Jul 2020 22:47:43 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Mon, 6 Jul 2020 22:31:58 GMT, Igor Ignatyev wrote: >> I guess this is a question for those who normally handle fix verification and may have scripts that look for different >> verifications. >> There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". >> "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not >> verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed >> out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs >> verification. So changing to using this would probably cause problems. That leaves "Fix failed". Maybe Joe knows why >> this was designed as it is? Anyhow, it is the current process and we need to bring it up with the right people before >> changing it. > > AFAIK, The verification process isn't part of any OpenJDK process and is used/done mainly internally by Oracle. why do > you think that verification status should be set for all backed out issues? The text is based on an ancient definition of how to back out changes. That text was JDK wide (not only HotSpot) but yes, internal to Oracle. If verification is not important or done for all issues I'd be happy to remove that sentence. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From igor.ignatyev at oracle.com Mon Jul 6 22:56:45 2020 From: igor.ignatyev at oracle.com (Igor Ignatyev) Date: Mon, 6 Jul 2020 15:56:45 -0700 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> Message-ID: <511607F3-61AC-480B-9E3C-BD3791BBE33F@oracle.com> Hi David, > On Jul 6, 2020, at 3:41 PM, David Holmes wrote: > > Hi Igor, > > On 7/07/2020 8:36 am, Igor Ignatyev wrote: >> On Mon, 6 Jul 2020 22:25:58 GMT, Jesper Wilhelmsson wrote: >>>> src/next.md line 154: >>>> >>>>> 153: #. Close the original JBS issue **(O)**. >>>>> 154: * "Verify" the issue and choose "Fix Failed". >>>>> 155: #. If the intention is to fix the change and submit it again, create a redo-issue **(R)** to track that the work >>>>> still needs to be done. >>>> >>>> I have strong objections to fix failed ever being used and oppose it being recommended here. Unless the fixer and their >>>> reviewers completely failed at their job what you usually have is some other problem caused by the fix and the fix >>>> actually succeeded. >>> >>> I guess this is a question for those who normally handle fix verification and may have scripts that look for different >>> verifications. >>> There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". >>> "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not >>> verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed >>> out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs >>> verification. So changing to using this would probably cause problems. That leaves "Fix failed". Maybe Joe knows why >>> this was designed as it is? Anyhow, it is the current process and we need to bring it up with the right people before >>> changing it. >> AFAIK, The verification process isn't part of any OpenJDK process and is used/done mainly internally by Oracle. why do >> you think that verification status should be set for all backed out issues? > > That was the process that was defined. If a fix has to be backed out then the fix is considered to have "failed". ok, but this meaning is a bit different from the one in the verification process, where - 'Verified' means that someone checked that the defect described in the issue has been addressed by the fix, and it actually was; - 'Fix failed' means that someone checked that the defect described in the issue has been addressed by the fix, but it actually was not, i.e. the defect still exists after the fix. Although, I personally don't see this difference as a big deal, yet I'd imagine that there are some metrics/criteria based on verification status, and inclusion of all backouts to the pile of 'Fix failed' might have some implications, so I'd recommend checking w/ people who track that sort of data (unless it has been already done when the backing out process has been established) (just for completeness), other verification statues: - 'Not verified' means that a) for some reasons, it has been decided not to verify the issue; or b) there were problems during verification, so it was impossible/hard to verify the issue; - 'None' is a default value, i.e. none has worked on the issue's verification -- Igor > David > ----- > >> ------------- >> PR: https://git.openjdk.java.net/guide/pull/21 From david.holmes at oracle.com Mon Jul 6 23:26:57 2020 From: david.holmes at oracle.com (David Holmes) Date: Tue, 7 Jul 2020 09:26:57 +1000 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <511607F3-61AC-480B-9E3C-BD3791BBE33F@oracle.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> <511607F3-61AC-480B-9E3C-BD3791BBE33F@oracle.com> Message-ID: <32179cb7-13bd-5847-616b-623bc8376fb8@oracle.com> On 7/07/2020 8:56 am, Igor Ignatyev wrote: > Hi David, > >> On Jul 6, 2020, at 3:41 PM, David Holmes > > wrote: >> >> Hi Igor, >> >> On 7/07/2020 8:36 am, Igor Ignatyev wrote: >>> On Mon, 6 Jul 2020 22:25:58 GMT, Jesper Wilhelmsson >>> > wrote: >>>>> src/next.md line 154: >>>>> >>>>>> 153: #. Close the original JBS issue **(O)**. >>>>>> 154: ???* "Verify" the issue and choose "Fix Failed". >>>>>> 155: #. If the intention is to fix the change and submit it again, >>>>>> create a redo-issue **(R)** to track that the work >>>>>> still needs to be done. >>>>> >>>>> I have strong objections to fix failed ever being used and oppose >>>>> it being recommended here. Unless the fixer and their >>>>> reviewers completely failed at their job what you usually have is >>>>> some other problem caused by the fix and the fix >>>>> actually succeeded. >>>> >>>> I guess this is a question for those who normally handle fix >>>> verification and may have scripts that look for different >>>> verifications. >>>> There's only four values to choose from: "None", "Verified", "Not >>>> verified", and "Fix failed". >>>> "Verified" means that the fix solved the problem and no more action >>>> is required, so this is clearly not right. "Not >>>> verified" seems wrong since it actually was verified that the fix >>>> caused problems - or it wouldn't need to be backed >>>> out. "None" could be used in my mind, but I can imagine that there >>>> are filters that treats "None" as issues that needs >>>> verification. So changing to using this would probably cause >>>> problems. That leaves "Fix failed". ?Maybe Joe knows why >>>> this was designed as it is? ?Anyhow, it is the current process and >>>> we need to bring it up with the right people before >>>> changing it. >>> AFAIK, The verification process isn't part of any OpenJDK process and >>> is used/done mainly internally by Oracle. why do >>> you think that verification status should be set for all backed out >>> issues? >> >> That was the process that was defined. If a fix has to be backed out >> then the fix is considered to have "failed". > > ok, but this meaning is a bit different from the one in the verification > process, where > ?- 'Verified' means that someone checked that the defect described in > the issue has been addressed by the fix, and it actually was; > ?- 'Fix failed' means that someone checked that the defect described in > the issue has been addressed by the fix, but it actually was not, i.e. > the defect still exists after the fix. I thought "fix failed" was more broadly defined as either not fixing the original issue, or introducing additional breakage. In terms of backports I would expect anything marked as "fix failed" to not be backported, and then the backout issue would also not be backported. But sometimes it isn't that simple. But these are just my recollections from the earlier definition of the backing out process. And as you note the Verification process is really an Oracle specific concept exposed in JBS. I'm not sure how to deal with that. There aren't really any guidelines on how to use JBS in the OpenJDK process docs. Cheers, David > > Although, I personally don't see this difference as a big deal, yet I'd > imagine that there are some metrics/criteria based on verification > status, and inclusion of all backouts to the pile of 'Fix failed' might > have some implications, so I'd recommend checking w/ people who track > that sort of data (unless it has been already done when the backing out > process has been established) > > (just for completeness), other verification statues: > ?- 'Not verified' means that a) for some reasons, it has been decided > not to verify the issue; or b) there were problems during verification, > so it was impossible/hard to verify the issue; > ?- 'None' is a default value, i.e. none has worked on the issue's > verification > > -- Igor > > >> David >> ----- >> >>> ------------- >>> PR:https://git.openjdk.java.net/guide/pull/21 > From igor.ignatyev at oracle.com Mon Jul 6 23:58:27 2020 From: igor.ignatyev at oracle.com (Igor Ignatyev) Date: Mon, 6 Jul 2020 16:58:27 -0700 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <32179cb7-13bd-5847-616b-623bc8376fb8@oracle.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> <511607F3-61AC-480B-9E3C-BD3791BBE33F@oracle.com> <32179cb7-13bd-5847-616b-623bc8376fb8@oracle.com> Message-ID: <03C47C59-2981-4B7B-B30D-5D7F94D13E96@oracle.com> > On Jul 6, 2020, at 4:26 PM, David Holmes wrote: > > On 7/07/2020 8:56 am, Igor Ignatyev wrote: >> Hi David, >>> On Jul 6, 2020, at 3:41 PM, David Holmes > wrote: >>> >>> Hi Igor, >>> >>> On 7/07/2020 8:36 am, Igor Ignatyev wrote: >>>> On Mon, 6 Jul 2020 22:25:58 GMT, Jesper Wilhelmsson > wrote: >>>>>> src/next.md line 154: >>>>>> >>>>>>> 153: #. Close the original JBS issue **(O)**. >>>>>>> 154: * "Verify" the issue and choose "Fix Failed". >>>>>>> 155: #. If the intention is to fix the change and submit it again, create a redo-issue **(R)** to track that the work >>>>>>> still needs to be done. >>>>>> >>>>>> I have strong objections to fix failed ever being used and oppose it being recommended here. Unless the fixer and their >>>>>> reviewers completely failed at their job what you usually have is some other problem caused by the fix and the fix >>>>>> actually succeeded. >>>>> >>>>> I guess this is a question for those who normally handle fix verification and may have scripts that look for different >>>>> verifications. >>>>> There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". >>>>> "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not >>>>> verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed >>>>> out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs >>>>> verification. So changing to using this would probably cause problems. That leaves "Fix failed". Maybe Joe knows why >>>>> this was designed as it is? Anyhow, it is the current process and we need to bring it up with the right people before >>>>> changing it. >>>> AFAIK, The verification process isn't part of any OpenJDK process and is used/done mainly internally by Oracle. why do >>>> you think that verification status should be set for all backed out issues? >>> >>> That was the process that was defined. If a fix has to be backed out then the fix is considered to have "failed". >> ok, but this meaning is a bit different from the one in the verification process, where >> - 'Verified' means that someone checked that the defect described in the issue has been addressed by the fix, and it actually was; >> - 'Fix failed' means that someone checked that the defect described in the issue has been addressed by the fix, but it actually was not, i.e. the defect still exists after the fix. > > I thought "fix failed" was more broadly defined as either not fixing the original issue, or introducing additional breakage. disclaimer: I haven't had a chance to find a define process description, so all above and below are my recollections of the bug fix verification process. it's not the goal of bug fix verification to see if there are any new regression/breakages introduced by the fix (that would be a goal of testing). the verification process is only concerned if the original defect has been fixed, alhought it's subject to interpretation and can mean anything from 'the newly added regression test passes with the patch, and fails without', through 'the described customer's issue can't be reproduced with the patch', to 'the defect and all its variations in the codebase have been identified, isolated and verified that they do not manifest with the patch', but it never includes 'the product's quality is better than it was before', 'no new bugs were introduced', etc as such analysis is, generally speaking, infeasible. with that being said, for the cases when the patch has been backed out, the original defect is clearly still exists in the product, so it fits the definition, but only if there was a defect. in other words, it doesn't fit (well) for RFEs, as there is no defect to fix, hence no way to verify it has been fixed (unless you stretch the definitions of "defect"). -- Igor PS I have noticed that this email thread hasn't been added to the PR by skara's bots. > > In terms of backports I would expect anything marked as "fix failed" to not be backported, and then the backout issue would also not be backported. But sometimes it isn't that simple. > > But these are just my recollections from the earlier definition of the backing out process. And as you note the Verification process is really an Oracle specific concept exposed in JBS. I'm not sure how to deal with that. There aren't really any guidelines on how to use JBS in the OpenJDK process docs. > > Cheers, > David > >> Although, I personally don't see this difference as a big deal, yet I'd imagine that there are some metrics/criteria based on verification status, and inclusion of all backouts to the pile of 'Fix failed' might have some implications, so I'd recommend checking w/ people who track that sort of data (unless it has been already done when the backing out process has been established) >> (just for completeness), other verification statues: >> - 'Not verified' means that a) for some reasons, it has been decided not to verify the issue; or b) there were problems during verification, so it was impossible/hard to verify the issue; >> - 'None' is a default value, i.e. none has worked on the issue's verification >> -- Igor >>> David >>> ----- >>> >>>> ------------- >>>> PR:https://git.openjdk.java.net/guide/pull/21 From prr at openjdk.java.net Mon Jul 6 20:12:07 2020 From: prr at openjdk.java.net (Phil Race) Date: Mon, 6 Jul 2020 20:12:07 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: On Fri, 3 Jul 2020 00:27:23 GMT, Jesper Wilhelmsson wrote: >> Filing bug, ProblemListing, Backing out > > Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: > > Fixed comments from review Changes requested by prr (no project role). src/next.md line 22: > 21: When a new failure is found in the JDK a bug should be filed to describe and track the issue. Depending on your > role in the OpenJDK you can either use the [Bug Report Tool](https://bugreport.java.com/) or, if you are Author in an > OpenJDK Project, report the bug directly in the [JDK Bug System](https://bugs.openjdk.java.net/). Try to make the bug > report as complete as possible to make it easier to triage and investigate the bug. It's not the reporter's > responsibility to set a correct priority, but a good guess is always better than a default value. To help with setting > the right priority consider things like how the bug impacts the product and our testing, how likely is it that the bug > triggers, and how difficult is it to work around the bug if it's not fixed soon. 22: 23: A few things to keep in mind > when filing a new bug: and whether it is a recent regression, since that may break existing applications. regressions are often higher priority than long standing bugs. src/next.md line 42: > 41: Sometimes tests break. It could be due to bugs in the test itself, or due to changed functionality in the code that > the test is testing. While working on a fix, it can be useful to stop the test from being executed in everyone else's > testing to reduce noise, especially if the test is expected to fail for more than a day. There are two ways to stop a > test from being run in standard test runs: ProblemListing and using the `@ignore` keyword. Removing tests isn't the > standard way to remove a failure. A failing test is expected to be a regression and should ideally be handled promptly > with high urgency. 42: 43: I'll say it right away so that it's not forgotten at the end: Remember to remove the JBS id > from the ProblemList or the test when the bug is closed. This is especially easy to forget if a bug is closed as a > duplicate or 'Will Not Fix'. this isn't the whole picture A test may fail because it is now being tested in new environment, (eg new platform or platform release) not just because of the afore stated reasons. This would not be a regression but might still be important. src/next.md line 48: > 47: ProblemListing is used for a short term exclusion while a test is being fixed, and for the exclusion of > intermittently failing tests that cause too much noise, but can still be useful to run on an ad-hoc basis. > ProblemListing is done in the file `ProblemList.txt`. There are actually several ProblemList files to choose from. > Their location and name hint about what area or feature each file belongs to. Each file has sections for different > components. All ProblemList files complement each other to build the total set of tests to exclude in JTReg runs. 48: > 49: ~~~ the emphasis that the exclusion is short lived is sadly unduly optimistic. Problem listing can be used for long term exclusions too. It is still better than deleting a valid test. src/next.md line 73: > 72: In this example, `MyTest.java` is ProblemListed on windows, tracked by bug `JDK-4711`. > 73: > 74: Currently there's [no support for multiple lines for the same > test](https://bugs.openjdk.java.net/browse/CODETOOLS-7902481). For this reason it's important to always make sure > there's no existing entry for the test before adding a new one, as multiple entries might lead to unexpected results, > e.g. Not sure where in this review to insert this but there is a sensible policy that you should make sure the bug report is open. If you are submitting it that is easy to ensure but there have been cases where bugs are closed (without necessarily being fixed) and the issue remains PL'd. A legitimate case where this occurs if a bug is fixed in one line of development but the fix is not (yet:?) backported and I'm not sure how the "sensible policy" accounts for that. src/next.md line 147: > 146: > 147: If a change cause a regression that can't be fixed within reasonable time the best way to handle the regression > can be to back out the change. Backing out means that the inverse (anti-delta) of the change is pushed to effectively > undo the change in the repository. There are two parts to this task, how to do the bookkeeping in JBS, and how to do > the actual backout in mercurial. 148: cause -> causes src/next.md line 149: > 148: > 149: The backout is a regular change and will have to go through the standard code review process, but is considered a > trivial change and thus it requires only one Reviewer and will avoid the 24h code review window, even for areas where > stricter rules usually applies. The rationale is that a backout is usually urgent in nature and the change itself is > automatically created by hg, and reviewed by the person who is performing the backout, so even though only one > additional Reviewer is required the change will in practice get two reviews. 150: where is the 24h code review window discussed ? It might be a sensible policy for non-urgent fixes but I've never seen it documented/codified and we've never had it as a rule in the client area. src/next.md line 154: > 153: #. Close the original JBS issue **(O)**. > 154: * "Verify" the issue and choose "Fix Failed". > 155: #. If the intention is to fix the change and submit it again, create a redo-issue **(R)** to track that the work > still needs to be done. I have strong objections to fix failed ever being used and oppose it being recommended here. Unless the fixer and their reviewers completely failed at their job what you usually have is some other problem caused by the fix and the fix actually succeeded. ------------- PR: https://git.openjdk.java.net/guide/pull/21 From jesper.wilhelmsson at oracle.com Tue Jul 7 00:13:16 2020 From: jesper.wilhelmsson at oracle.com (Jesper Wilhelmsson) Date: Tue, 7 Jul 2020 02:13:16 +0200 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <03C47C59-2981-4B7B-B30D-5D7F94D13E96@oracle.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> <511607F3-61AC-480B-9E3C-BD3791BBE33F@oracle.com> <32179cb7-13bd-5847-616b-623bc8376fb8@oracle.com> <03C47C59-2981-4B7B-B30D-5D7F94D13E96@oracle.com> Message-ID: <5F46CC92-20E8-4A59-B108-927C7ACC2741@oracle.com> > On 7 Jul 2020, at 01:58, Igor Ignatyev wrote: >> On Jul 6, 2020, at 4:26 PM, David Holmes wrote: >> On 7/07/2020 8:56 am, Igor Ignatyev wrote: >>> Hi David, >>>> On Jul 6, 2020, at 3:41 PM, David Holmes > wrote: >>>> >>>> Hi Igor, >>>> >>>> On 7/07/2020 8:36 am, Igor Ignatyev wrote: >>>>> On Mon, 6 Jul 2020 22:25:58 GMT, Jesper Wilhelmsson > wrote: >>>>>>> src/next.md line 154: >>>>>>> >>>>>>>> 153: #. Close the original JBS issue **(O)**. >>>>>>>> 154: * "Verify" the issue and choose "Fix Failed". >>>>>>>> 155: #. If the intention is to fix the change and submit it again, create a redo-issue **(R)** to track that the work >>>>>>>> still needs to be done. >>>>>>> >>>>>>> I have strong objections to fix failed ever being used and oppose it being recommended here. Unless the fixer and their >>>>>>> reviewers completely failed at their job what you usually have is some other problem caused by the fix and the fix >>>>>>> actually succeeded. >>>>>> >>>>>> I guess this is a question for those who normally handle fix verification and may have scripts that look for different >>>>>> verifications. >>>>>> There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". >>>>>> "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not >>>>>> verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed >>>>>> out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs >>>>>> verification. So changing to using this would probably cause problems. That leaves "Fix failed". Maybe Joe knows why >>>>>> this was designed as it is? Anyhow, it is the current process and we need to bring it up with the right people before >>>>>> changing it. >>>>> AFAIK, The verification process isn't part of any OpenJDK process and is used/done mainly internally by Oracle. why do >>>>> you think that verification status should be set for all backed out issues? >>>> >>>> That was the process that was defined. If a fix has to be backed out then the fix is considered to have "failed". >>> ok, but this meaning is a bit different from the one in the verification process, where >>> - 'Verified' means that someone checked that the defect described in the issue has been addressed by the fix, and it actually was; >>> - 'Fix failed' means that someone checked that the defect described in the issue has been addressed by the fix, but it actually was not, i.e. the defect still exists after the fix. >> >> I thought "fix failed" was more broadly defined as either not fixing the original issue, or introducing additional breakage. > disclaimer: I haven't had a chance to find a define process description, so all above and below are my recollections of the bug fix verification process. > > it's not the goal of bug fix verification to see if there are any new regression/breakages introduced by the fix (that would be a goal of testing). the verification process is only concerned if the original defect has been fixed, alhought it's subject to interpretation and can mean anything from 'the newly added regression test passes with the patch, and fails without', through 'the described customer's issue can't be reproduced with the patch', to 'the defect and all its variations in the codebase have been identified, isolated and verified that they do not manifest with the patch', but it never includes 'the product's quality is better than it was before', 'no new bugs were introduced', etc as such analysis is, generally speaking, infeasible. with that being said, for the cases when the patch has been backed out, the original defect is clearly still exists in the product, so it fits the definition, but only if there was a defect. in other words, it doesn't fit (well) for RFEs, as there is no defect to fix, hence no way to verify it has been fixed (unless you stretch the definitions of "defect"). I have passed the question on to people who should be able to answer how this is being used and if it matters all that much. We'll see what they say. Anyhow, the Oracle internal process is as described here to use "Fix failed". A valid question is if we should document this at all here, but documenting something else will not change the internal Oracle process. We need to bring the question to a different forum to do that. > -- Igor > > PS I have noticed that this email thread hasn't been added to the PR by skara's bots. I noticed the same. I wonder if it's related to the openjdk.java.net problems that we saw earlier. I could access the mail-list admin page now so that problem seems to be fixed at least. But some bot might need a reboot to get the sync to work again. /Jesper > > >> >> In terms of backports I would expect anything marked as "fix failed" to not be backported, and then the backout issue would also not be backported. But sometimes it isn't that simple. >> >> But these are just my recollections from the earlier definition of the backing out process. And as you note the Verification process is really an Oracle specific concept exposed in JBS. I'm not sure how to deal with that. There aren't really any guidelines on how to use JBS in the OpenJDK process docs. >> >> Cheers, >> David >> >>> Although, I personally don't see this difference as a big deal, yet I'd imagine that there are some metrics/criteria based on verification status, and inclusion of all backouts to the pile of 'Fix failed' might have some implications, so I'd recommend checking w/ people who track that sort of data (unless it has been already done when the backing out process has been established) >>> (just for completeness), other verification statues: >>> - 'Not verified' means that a) for some reasons, it has been decided not to verify the issue; or b) there were problems during verification, so it was impossible/hard to verify the issue; >>> - 'None' is a default value, i.e. none has worked on the issue's verification >>> -- Igor >>>> David >>>> ----- >>>> >>>>> ------------- >>>>> PR:https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Tue Jul 7 01:24:56 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Tue, 7 Jul 2020 01:24:56 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v4] In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: > Filing bug, ProblemListing, Backing out Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: Added 'trivial' to the glossary and fixed Phil's comments ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/21/files - new: https://git.openjdk.java.net/guide/pull/21/files/6bd69e06..fd1a760e Webrevs: - full: https://webrevs.openjdk.java.net/guide/21/webrev.03 - incr: https://webrevs.openjdk.java.net/guide/21/webrev.02-03 Stats: 10 lines in 2 files changed: 3 ins; 0 del; 7 mod Patch: https://git.openjdk.java.net/guide/pull/21.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/21/head:pull/21 PR: https://git.openjdk.java.net/guide/pull/21 From jwilhelm at openjdk.java.net Tue Jul 7 16:19:45 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Tue, 7 Jul 2020 16:19:45 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v5] In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: <7ZwdqRhDqVL9h1GPdnOod_EoXCbO6TvimFQkX2mXY58=.e7efb337-adbc-4702-9244-bebace49c73b@github.com> > Filing bug, ProblemListing, Backing out Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: Removed Verify-step from backing out description ------------- Changes: - all: https://git.openjdk.java.net/guide/pull/21/files - new: https://git.openjdk.java.net/guide/pull/21/files/fd1a760e..30ace751 Webrevs: - full: https://webrevs.openjdk.java.net/guide/21/webrev.04 - incr: https://webrevs.openjdk.java.net/guide/21/webrev.03-04 Stats: 3 lines in 1 file changed: 0 ins; 2 del; 1 mod Patch: https://git.openjdk.java.net/guide/pull/21.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/21/head:pull/21 PR: https://git.openjdk.java.net/guide/pull/21 From joe.darcy at oracle.com Wed Jul 8 02:34:08 2020 From: joe.darcy at oracle.com (Joe Darcy) Date: Tue, 7 Jul 2020 19:34:08 -0700 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> Message-ID: <09e9d8d7-35c6-34ea-935c-b562948c1e53@oracle.com> Hello, Reply interspersed below... On 7/6/2020 3:28 PM, Jesper Wilhelmsson wrote: > On Mon, 6 Jul 2020 20:09:30 GMT, Phil Race wrote: > [snip] > I guess this is a question for those who normally handle fix verification and may have scripts that look for different > verifications. > > There's only four values to choose from: "None", "Verified", "Not verified", and "Fix failed". > "Verified" means that the fix solved the problem and no more action is required, so this is clearly not right. "Not > verified" seems wrong since it actually was verified that the fix caused problems - or it wouldn't need to be backed > out. "None" could be used in my mind, but I can imagine that there are filters that treats "None" as issues that needs > verification. So changing to using this would probably cause problems. That leaves "Fix failed". > > Maybe Joe knows why this was designed as it is? Anyhow, it is the current process and we need to bring it up with the > right people before changing it. To condense a longer narrative, the verification field was added at the behest of Oracle's JDK SQE organization and that organization generally manages setting the field. The most typically outcome is "Verified" once the regression tests associated with a fix are seen to pass. In exceptional cases, there are conditions where a fix is marked as failed. I suggesting focusing on other aspects of bug management besides verification. HTH, -Joe From joe.darcy at oracle.com Wed Jul 8 02:36:59 2020 From: joe.darcy at oracle.com (Joe Darcy) Date: Tue, 7 Jul 2020 19:36:59 -0700 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: <32179cb7-13bd-5847-616b-623bc8376fb8@oracle.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> <511607F3-61AC-480B-9E3C-BD3791BBE33F@oracle.com> <32179cb7-13bd-5847-616b-623bc8376fb8@oracle.com> Message-ID: On 7/6/2020 4:26 PM, David Holmes wrote: > On 7/07/2020 8:56 am, Igor Ignatyev wrote: >> Hi David, >> >>> On Jul 6, 2020, at 3:41 PM, David Holmes >> > wrote: >>> >>> Hi Igor, >>> >>> On 7/07/2020 8:36 am, Igor Ignatyev wrote: >>>> On Mon, 6 Jul 2020 22:25:58 GMT, Jesper Wilhelmsson >>>> > wrote: >>>>>> src/next.md line 154: >>>>>> >>>>>>> 153: #. Close the original JBS issue **(O)**. >>>>>>> 154: ???* "Verify" the issue and choose "Fix Failed". >>>>>>> 155: #. If the intention is to fix the change and submit it >>>>>>> again, create a redo-issue **(R)** to track that the work >>>>>>> still needs to be done. >>>>>> >>>>>> I have strong objections to fix failed ever being used and oppose >>>>>> it being recommended here. Unless the fixer and their >>>>>> reviewers completely failed at their job what you usually have is >>>>>> some other problem caused by the fix and the fix >>>>>> actually succeeded. >>>>> >>>>> I guess this is a question for those who normally handle fix >>>>> verification and may have scripts that look for different >>>>> verifications. >>>>> There's only four values to choose from: "None", "Verified", "Not >>>>> verified", and "Fix failed". >>>>> "Verified" means that the fix solved the problem and no more >>>>> action is required, so this is clearly not right. "Not >>>>> verified" seems wrong since it actually was verified that the fix >>>>> caused problems - or it wouldn't need to be backed >>>>> out. "None" could be used in my mind, but I can imagine that there >>>>> are filters that treats "None" as issues that needs >>>>> verification. So changing to using this would probably cause >>>>> problems. That leaves "Fix failed". ?Maybe Joe knows why >>>>> this was designed as it is? ?Anyhow, it is the current process and >>>>> we need to bring it up with the right people before >>>>> changing it. >>>> AFAIK, The verification process isn't part of any OpenJDK process >>>> and is used/done mainly internally by Oracle. why do >>>> you think that verification status should be set for all backed out >>>> issues? >>> >>> That was the process that was defined. If a fix has to be backed out >>> then the fix is considered to have "failed". >> >> ok, but this meaning is a bit different from the one in the >> verification process, where >> ??- 'Verified' means that someone checked that the defect described >> in the issue has been addressed by the fix, and it actually was; >> ??- 'Fix failed' means that someone checked that the defect described >> in the issue has been addressed by the fix, but it actually was not, >> i.e. the defect still exists after the fix. > > I thought "fix failed" was more broadly defined as either not fixing > the original issue, or introducing additional breakage. > > In terms of backports I would expect anything marked as "fix failed" > to not be backported, and then the backout issue would also not be > backported. But sometimes it isn't that simple. > > But these are just my recollections from the earlier definition of the > backing out process. And as you note the Verification process is > really an Oracle specific concept exposed in JBS. I'm not sure how to > deal with that. There aren't really any guidelines on how to use JBS > in the OpenJDK process docs. > Admittedly it isn't easy to find, but there is a bit written about using JBS in the OpenJDK wiki: ??? https://wiki.openjdk.java.net/display/general/JBS+Overview -Joe From david.holmes at oracle.com Wed Jul 8 07:47:38 2020 From: david.holmes at oracle.com (David Holmes) Date: Wed, 8 Jul 2020 17:47:38 +1000 Subject: RFR: Filing bug, ProblemListing, Backing out [v2] In-Reply-To: References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <4c0ffe1c-214e-6974-5578-94b3620d3fb7@oracle.com> <511607F3-61AC-480B-9E3C-BD3791BBE33F@oracle.com> <32179cb7-13bd-5847-616b-623bc8376fb8@oracle.com> Message-ID: <6060da8b-b69d-1685-9544-cdaabb370a5b@oracle.com> On 8/07/2020 12:36 pm, Joe Darcy wrote: > On 7/6/2020 4:26 PM, David Holmes wrote: >> There aren't really any guidelines on how to use JBS >> in the OpenJDK process docs. >> > > Admittedly it isn't easy to find, but there is a bit written about using > JBS in the OpenJDK wiki: > > ??? https://wiki.openjdk.java.net/display/general/JBS+Overview Thanks for that Joe! Might be a little easier to find if it were obvious when there exist "sub-topics" under the main item. Otherwise I would never think to click on "About" to see "JBS Overview" David > -Joe > From github.com+5994243+aioobe at openjdk.java.net Wed Jul 8 09:34:44 2020 From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad) Date: Wed, 8 Jul 2020 09:34:44 GMT Subject: RFR: Css updates Message-ID: * Added styling for code blocks and info boxes. * Joined code blocks into a single one in hgHelp and tClone. ------------- Commit messages: - Joined code blocks into a single one in hgHelp and tClone. - Added styling for code blocks and info boxes. Changes: https://git.openjdk.java.net/guide/pull/22/files Webrev: https://webrevs.openjdk.java.net/guide/22/webrev.00 Stats: 50 lines in 3 files changed: 32 ins; 0 del; 18 mod Patch: https://git.openjdk.java.net/guide/pull/22.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/22/head:pull/22 PR: https://git.openjdk.java.net/guide/pull/22 From jwilhelm at openjdk.java.net Wed Jul 8 21:23:43 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Wed, 8 Jul 2020 21:23:43 GMT Subject: RFR: Css updates In-Reply-To: References: Message-ID: On Wed, 8 Jul 2020 09:19:48 GMT, Andreas Lundblad wrote: > * Added styling for code blocks and info boxes. > * Joined code blocks into a single one in hgHelp and tClone. Thank you for making these changes! ------------- Marked as reviewed by jwilhelm (Lead). PR: https://git.openjdk.java.net/guide/pull/22 From github.com+5994243+aioobe at openjdk.java.net Wed Jul 8 23:43:03 2020 From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad) Date: Wed, 8 Jul 2020 23:43:03 GMT Subject: Integrated: Css updates In-Reply-To: References: Message-ID: On Wed, 8 Jul 2020 09:19:48 GMT, Andreas Lundblad wrote: > * Added styling for code blocks and info boxes. > * Joined code blocks into a single one in hgHelp and tClone. This pull request has now been integrated. Changeset: 7704733c Author: Andreas Lundblad Committer: Jesper Wilhelmsson URL: https://git.openjdk.java.net/guide/commit/7704733c Stats: 50 lines in 3 files changed: 0 ins; 32 del; 18 mod Css updates Reviewed-by: jwilhelm ------------- PR: https://git.openjdk.java.net/guide/pull/22 From jwilhelm at openjdk.java.net Thu Jul 9 05:10:54 2020 From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson) Date: Thu, 9 Jul 2020 05:10:54 GMT Subject: RFR: Use https for all links Message-ID: Use https for all links ------------- Commit messages: - Use https for all links Changes: https://git.openjdk.java.net/guide/pull/23/files Webrev: https://webrevs.openjdk.java.net/guide/23/webrev.00 Stats: 55 lines in 8 files changed: 0 ins; 0 del; 55 mod Patch: https://git.openjdk.java.net/guide/pull/23.diff Fetch: git fetch https://git.openjdk.java.net/guide pull/23/head:pull/23 PR: https://git.openjdk.java.net/guide/pull/23 From iris at openjdk.java.net Thu Jul 9 06:27:11 2020 From: iris at openjdk.java.net (Iris Clark) Date: Thu, 9 Jul 2020 06:27:11 GMT Subject: RFR: Use https for all links In-Reply-To: References: Message-ID: On Thu, 9 Jul 2020 05:01:28 GMT, Jesper Wilhelmsson wrote: > Use https for all links src/glossary.md line 46: > 45: The main Mercurial documentation is available at > 46: [https://hgbook.red-bean.com](https://hgbook.red-bean.com/). > 47: red-bean.com either doesn't support https or has a bad certificate. Recommend this remain as "http" to avoid broken link. src/producingChangeset.md line 33: > 32: required and a new changeset may be required to correct previous mistakes. The > 33: [mq extension](https://hgbook.red-bean.com/hgbookch12.html#x16-26500012) is > 34: recommended for managing changes before they become red-bean.com does not appear to support https ------------- PR: https://git.openjdk.java.net/guide/pull/23 From iignatyev at openjdk.java.net Thu Jul 9 06:37:03 2020 From: iignatyev at openjdk.java.net (Igor Ignatyev) Date: Thu, 9 Jul 2020 06:37:03 GMT Subject: RFR: Filing bug, ProblemListing, Backing out [v5] In-Reply-To: <7ZwdqRhDqVL9h1GPdnOod_EoXCbO6TvimFQkX2mXY58=.e7efb337-adbc-4702-9244-bebace49c73b@github.com> References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com> <7ZwdqRhDqVL9h1GPdnOod_EoXCbO6TvimFQkX2mXY58=.e7efb337-adbc-4702-9244-bebace49c73b@github.com> Message-ID: <4liKldJ0Jdf4F-89omNV2xOTekbd1SdQgiJkymseioE=.97388cb4-2f1f-4f0f-a504-c2813dc50ae5@github.com> On Tue, 7 Jul 2020 16:19:45 GMT, Jesper Wilhelmsson wrote: >> Filing bug, ProblemListing, Backing out > > Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision: > > Removed Verify-step from backing out description Marked as reviewed by iignatyev (no project role). ------------- PR: https://git.openjdk.java.net/guide/pull/21 From iris at openjdk.java.net Thu Jul 9 06:32:49 2020 From: iris at openjdk.java.net (Iris Clark) Date: Thu, 9 Jul 2020 06:32:49 GMT Subject: RFR: Use https for all links In-Reply-To: References: Message-ID: On Thu, 9 Jul 2020 05:01:28 GMT, Jesper Wilhelmsson wrote: > Use https for all links The red-bean.com links appear to be broken using "https". Consider continued use of "http" for these cases. ------------- Marked as reviewed by iris (Reviewer). PR: https://git.openjdk.java.net/guide/pull/23 From github.com+5994243+aioobe at openjdk.java.net Thu Jul 9 09:46:57 2020 From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad) Date: Thu, 9 Jul 2020 09:46:57 GMT Subject: RFR: Removed blockquote formatting for code blocks. Message-ID: Blockquotes were used to format code blocks. With proper styling for `
` blocks this is no longer needed.

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

Commit messages:
 - Removed blockquote formatting for code blocks.

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

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

From jwilhelm at openjdk.java.net  Thu Jul  9 18:27:10 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 9 Jul 2020 18:27:10 GMT
Subject: RFR: Use https for all links [v2]
In-Reply-To: 
References: 
Message-ID: 

> Use https for all links

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

  Use http for red-bean links

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

Changes:
  - all: https://git.openjdk.java.net/guide/pull/23/files
  - new: https://git.openjdk.java.net/guide/pull/23/files/34cde267..49d6a661

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

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

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

From jwilhelm at openjdk.java.net  Thu Jul  9 18:27:19 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 9 Jul 2020 18:27:19 GMT
Subject: Integrated: Use https for all links
In-Reply-To: 
References: 
Message-ID: 

On Thu, 9 Jul 2020 05:01:28 GMT, Jesper Wilhelmsson  wrote:

> Use https for all links

This pull request has now been integrated.

Changeset: ba1a32b5
Author:    Jesper Wilhelmsson 
URL:       https://git.openjdk.java.net/guide/commit/ba1a32b5
Stats:     51 lines in 8 files changed: 0 ins; 0 del; 51 mod

Use https for all links

Reviewed-by: iris

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

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

From jwilhelm at openjdk.java.net  Thu Jul  9 19:33:14 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 9 Jul 2020 19:33:14 GMT
Subject: RFR: Use https for all links [v2]
In-Reply-To: 
References: 
 
Message-ID: 

On Thu, 9 Jul 2020 06:30:45 GMT, Iris Clark  wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Use http for red-bean links
>
> The red-bean.com links appear to be broken using "https".  Consider continued use of "http" for these cases.

Thanks for reviewing Iris!

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

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

From jwilhelm at openjdk.java.net  Thu Jul  9 23:04:17 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 9 Jul 2020 23:04:17 GMT
Subject: RFR: Removed blockquote formatting for code blocks.
In-Reply-To: 
References: 
Message-ID: 

On Thu, 9 Jul 2020 09:37:10 GMT, Andreas Lundblad  wrote:

> Blockquotes were used to format code blocks. With proper styling for `
` blocks this is no longer needed.

Looks good!

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

Marked as reviewed by jwilhelm (Lead).

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

From mark.reinhold at oracle.com  Thu Jul  9 23:51:33 2020
From: mark.reinhold at oracle.com (mark.reinhold at oracle.com)
Date: Thu, 09 Jul 2020 16:51:33 -0700
Subject: RFR: Updated section on Code Conventions.
In-Reply-To: 
References: 
 <20200622094020.797147833@eggemoggin.niobe.net>
 <15690ebb-6f03-9014-33fb-7c62f458cdc5@oracle.com>
 
 
 
 
 <33317468-7359-b1d1-aa05-0ce673128a2a@oracle.com>
 
 <1fb7cf56-8eb5-b73f-8fd2-8a5f852af40a@oracle.com>
 <4A71B635-C45D-4F95-92A1-33F810CFA8F6@ORACLE.COM>
 
Message-ID: <20200709165133.836046289@eggemoggin.niobe.net>

2020/7/2 10:47:52 -0700, jesper.wilhelmsson at oracle.com:
> I'll make an attempt at summarizing this discussion so far. There are
> a few issues that seems to be key to decide where a Style Guide can be
> located, all of them have pros and cons. The list below is not sorted
> in any way.

Thanks for putting this list together.  I think you?ve captured most of
the salient issues.  I agree with some but not all of your minor points,
but rather than discuss those here I?ll just mention one missing issue.

> ...
> 
> 2) Small, controlled, set of editors

Here?s the missing issue: Who would this set of editors be?  As I wrote
earlier:

  Not only would we need an editor to spend time on this, and maintain
  it for the long haul, but it would inevitably require some of the
  limited time of at least some of our most experienced contributors.
  Is that the best use of their time?

I don?t know how to answer this question but I don?t see any qualified
contributors volunteering, and I certainly can?t take it on myself.

Without an answer to this question, all the others are moot.

- Mark

From jwilhelm at openjdk.java.net  Fri Jul 10 00:17:04 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Fri, 10 Jul 2020 00:17:04 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v2]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
 
 
 
Message-ID: 

On Mon, 6 Jul 2020 22:44:40 GMT, Jesper Wilhelmsson  wrote:

>> AFAIK, The verification process isn't part of any OpenJDK process and is used/done mainly internally by Oracle. why do
>> you think that verification status should be set for all backed out issues?
>
> The text is based on an ancient definition of how to back out changes. That text was JDK wide (not only HotSpot) but
> yes, internal to Oracle. If verification is not important or done for all issues I'd be happy to remove that sentence.

There has been a longer discussion in the email thread on guide-dev that for some reason hasn't been copied here. From
that and other discussions I now have a directive on this issue; The verification field is both useful and used, also
for non-Oracle issues. It's not an Oracle internal field and anyone in the community can use it - it's actually
documented on the OpenJDK wiki even though it's not always easy to find information in a wiki. For this reason it's
actually even more important to clarify how it's intended to be used in the cases where we use it. Therefore we should
include the verification part in this description as it is part of the process.

As for using "Fix failed"; this was very well explained by Igor in the same mail thread: this is the value that means
that the bug still exists - and it does since the fix was backed out. It doesn't mean that the fix itself was bad or
broken.

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

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

From jwilhelm at openjdk.java.net  Fri Jul 10 00:38:36 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Fri, 10 Jul 2020 00:38:36 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
Message-ID: 

> Filing bug, ProblemListing, Backing out

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

  Put back Verify step in backout description.

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

Changes:
  - all: https://git.openjdk.java.net/guide/pull/21/files
  - new: https://git.openjdk.java.net/guide/pull/21/files/30ace751..37cebc84

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/21/webrev.05
 - incr: https://webrevs.openjdk.java.net/guide/21/webrev.04-05

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

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

From iignatyev at openjdk.java.net  Fri Jul 10 00:40:51 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Fri, 10 Jul 2020 00:40:51 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
Message-ID: 

On Fri, 10 Jul 2020 00:38:36 GMT, Jesper Wilhelmsson  wrote:

>> Filing bug, ProblemListing, Backing out
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Put back Verify step in backout description.

still LGTM

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

Marked as reviewed by iignatyev (no project role).

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

From iignatyev at openjdk.java.net  Fri Jul 10 00:40:51 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Fri, 10 Jul 2020 00:40:51 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v2]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
 
 
 
 
Message-ID: <8vAr38NJYRE0YCWQj4If2VlgJKJ6n5_yYCoTKZNaN4U=.e5828e3a-7152-4402-8127-c7e0db3e1477@github.com>

On Fri, 10 Jul 2020 00:14:58 GMT, Jesper Wilhelmsson  wrote:

>> The text is based on an ancient definition of how to back out changes. That text was JDK wide (not only HotSpot) but
>> yes, internal to Oracle. If verification is not important or done for all issues I'd be happy to remove that sentence.
>
> There has been a longer discussion in the email thread on guide-dev that for some reason hasn't been copied here. From
> that and other discussions I now have a directive on this issue; The verification field is both useful and used, also
> for non-Oracle issues. It's not an Oracle internal field and anyone in the community can use it - it's actually
> documented on the OpenJDK wiki even though it's not always easy to find information in a wiki. For this reason it's
> actually even more important to clarify how it's intended to be used in the cases where we use it. Therefore we should
> include the verification part in this description as it is part of the process.  As for using "Fix failed"; this was
> very well explained by Igor in the same mail thread: this is the value that means that the bug still exists - and it
> does since the fix was backed out. It doesn't mean that the fix itself was bad or broken.

just for the record, the email thread @JesperIRL referred to starts
[here](https://mail.openjdk.java.net/pipermail/guide-dev/2020-July/000192.html).

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

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

From github.com+5994243+aioobe at openjdk.java.net  Fri Jul 10 07:13:22 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Fri, 10 Jul 2020 07:13:22 GMT
Subject: RFR: Removed blockquote formatting for code blocks. [v2]
In-Reply-To: 
References: 
Message-ID: 

> Blockquotes were used to format code blocks. With proper styling for `
` blocks this is no longer needed.

Andreas Lundblad has updated the pull request with a new target base due to a merge or a rebase. The pull request now
contains two commits:

 - Merge master
 - Removed blockquote formatting for code blocks.

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

Changes: https://git.openjdk.java.net/guide/pull/24/files
 Webrev: https://webrevs.openjdk.java.net/guide/24/webrev.01
  Stats: 436 lines in 7 files changed: 0 ins; 0 del; 436 mod
  Patch: https://git.openjdk.java.net/guide/pull/24.diff
  Fetch: git fetch https://git.openjdk.java.net/guide pull/24/head:pull/24

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

From github.com+5994243+aioobe at openjdk.java.net  Fri Jul 10 15:46:00 2020
From: github.com+5994243+aioobe at openjdk.java.net (Andreas Lundblad)
Date: Fri, 10 Jul 2020 15:46:00 GMT
Subject: Integrated: Removed blockquote formatting for code blocks.
In-Reply-To: 
References: 
Message-ID: <0vBKVRUCePo1lf32KO38Ju7Syb-pDNcubYXI7rvEmFM=.0f5b1ce0-f384-4fa8-a990-0b3b0b96a152@github.com>

On Thu, 9 Jul 2020 09:37:10 GMT, Andreas Lundblad  wrote:

> Blockquotes were used to format code blocks. With proper styling for `
` blocks this is no longer needed.

This pull request has now been integrated.

Changeset: c44972d3
Author:    Andreas Lundblad 
Committer: Jesper Wilhelmsson 
URL:       https://git.openjdk.java.net/guide/commit/c44972d3
Stats:     436 lines in 7 files changed: 0 ins; 0 del; 436 mod

Removed blockquote formatting for code blocks.

Reviewed-by: jwilhelm

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

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

From iignatyev at openjdk.java.net  Tue Jul 14 14:54:39 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Tue, 14 Jul 2020 14:54:39 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
 
Message-ID: 

On Tue, 14 Jul 2020 06:20:22 GMT, Alan Bateman  wrote:

>> still LGTM
>
> Filing a Bug - are you going to say anything about checking if the issue exists in the main line, esp. with
> reproducible issues? Also what about advice on attaching a reproducer if possible?
> "ProblemListing or `@ignore`-ing a Test".  The ProblemList.txt files are jtreg exclude list. Can this section be
> renamed to "How to exclude tests"?  I don't think we've used "@ignore" for long time and might it simpler to just not
> mention it.

Hi @AlanBateman,
> I don't think we've used "@ignore" for long time and might it simpler to just not mention it.

`@ignore` is still used, albeit not very often, in hotspot tests for cases similar to the ones described here; given we
are seldomly running ProblemList-ed tests, it would be really unfortunate to have include tests which remove
`/etc/shadow` in such runs.

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

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

From Alan.Bateman at oracle.com  Tue Jul 14 15:12:03 2020
From: Alan.Bateman at oracle.com (Alan Bateman)
Date: Tue, 14 Jul 2020 16:12:03 +0100
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
 
 
Message-ID: 

On 14/07/2020 15:54, Igor Ignatyev wrote:
> :
> `@ignore` is still used, albeit not very often, in hotspot tests for cases similar to the ones described here; given we
> are seldomly running ProblemList-ed tests, it would be really unfortunate to have include tests which remove
> `/etc/shadow` in such runs.
>
A test that attempts to remove /etc/shadow sounds like a dangerous test. 
I remember there was one test in the libs areas but it has been fixed 
many years ago. I looked through the handful of tests that still have 
@ignore and the reasons aren't clear. Do you have examples of dangerous 
or other tests that aren't appropriate to put onto the jtreg exclude 
list? Only asking because it would be a lot simpler for everyone if 
there is one way to exclude tests.

-Alan

From igor.ignatyev at oracle.com  Tue Jul 14 17:01:53 2020
From: igor.ignatyev at oracle.com (Igor Ignatyev)
Date: Tue, 14 Jul 2020 10:01:53 -0700
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
 
 
 
Message-ID: <23B576E4-3199-45E2-BA8B-5A19173A6BBD@oracle.com>

> On Jul 14, 2020, at 8:12 AM, Alan Bateman  wrote:
> 
> On 14/07/2020 15:54, Igor Ignatyev wrote:
>> :
>> `@ignore` is still used, albeit not very often, in hotspot tests for cases similar to the ones described here; given we
>> are seldomly running ProblemList-ed tests, it would be really unfortunate to have include tests which remove
>> `/etc/shadow` in such runs.
>> 
> A test that attempts to remove /etc/shadow sounds like a dangerous test. I remember there was one test in the libs areas but it has been fixed many years ago. I looked through the handful of tests that still have @ignore and the reasons aren't clear. Do you have examples of dangerous or other tests that aren't appropriate to put onto the jtreg exclude list? Only asking because it would be a lot simpler for everyone if there is one way to exclude tests.
> 
> -Alan

Luckily, there is nothing as dangerous as removal of '/etc/shadow' left in our test suites now ;). There are, however, ~70 tests marked @ignore k/w, almost equally distributed among core-libs (40%), hotspot (30%), and langtools (30%) test suites. I looked thru the number of @ignore-d tests and, although, I haven't found any dangerous tests, there are some tests whose execution is completely useless or impossible till the associated bug gets addressed, e.g. 5 mlvm tests @ignore-d due to 8194951. And as you mentioned, some tests were excluded due to unclear reasons, so I would be very reluctant to use ProblemList instead of @ignore k/w for them. I'm also aware of tests that are in a ProblemList when they were to be @ignore-d, e.g. compiler/c2/Test6852078.java. I do agree that having two ways to achieve _nearly_ identical behavior is confusing. With that being said, I still think we need to have a way to exclude useless and/or harmful tests explicitly, so they don't get executed in our runs of ProblemList-ed tests. Hopefully, this guide will make it less confusing for people, and the right exclusion way (which in most cases is ProblemList) is going to be used more often.

PS  I'll embark on the quest for "canonicalization" of existed usages of problem-list and @ignore in all test suites, so the code doesn't contradict the guide.

-- Igor

From jwilhelm at openjdk.java.net  Thu Jul 23 18:41:54 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 23 Jul 2020 18:41:54 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v7]
In-Reply-To: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
Message-ID: 

> Filing bug, ProblemListing, Backing out

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

  Updated with Alan's suggestions

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

Changes:
  - all: https://git.openjdk.java.net/guide/pull/21/files
  - new: https://git.openjdk.java.net/guide/pull/21/files/37cebc84..83d5bbac

Webrevs:
 - full: https://webrevs.openjdk.java.net/guide/21/webrev.06
 - incr: https://webrevs.openjdk.java.net/guide/21/webrev.05-06

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

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

From jwilhelm at openjdk.java.net  Thu Jul 23 18:41:54 2020
From: jwilhelm at openjdk.java.net (Jesper Wilhelmsson)
Date: Thu, 23 Jul 2020 18:41:54 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
 
Message-ID: 

On Tue, 14 Jul 2020 06:20:22 GMT, Alan Bateman  wrote:

> Filing a Bug - are you going to say anything about checking if the issue exists in the main line, esp. with
> reproducible issues? Also what about advice on attaching a reproducer if possible?

Good suggestion! I have added both.

> "ProblemListing or `@ignore`-ing a Test". The ProblemList.txt files are jtreg exclude list. Can this section be renamed
> to "How to exclude tests"? I don't think we've used "@ignore" for long time and might it simpler to just not mention it.

I agree with changing the header of this section, and I do like "How to"-sections, but currently the guide doesn't have
this style so I suggest simply "Excluding a test".

As for the usage of `@ignore`; the keyword is used in ~100 tests, about a third in each of hotspot, jdk, and langtools,
so it's clearly used. I've added a few words to say that this is a less common use case, but I think the description as
such should remain.

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

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

From iignatyev at openjdk.java.net  Thu Jul 23 18:42:10 2020
From: iignatyev at openjdk.java.net (Igor Ignatyev)
Date: Thu, 23 Jul 2020 18:42:10 GMT
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
 
 
Message-ID: 

On Thu, 23 Jul 2020 18:20:10 GMT, Jesper Wilhelmsson  wrote:

> As for the usage of `@ignore`; the keyword is used in ~100 tests, about a third in each of hotspot, jdk, and langtools,
> so it's clearly used. I've added a few words to say that this is a less common use case, but I think the description as
> such should remain.

for the record, the discussion has continued on [the mailing
list](https://mail.openjdk.java.net/pipermail/guide-dev/2020-July/000225.html) (but due to some reasons hasn't been
bridged to this PR), [8249618](https://bugs.openjdk.java.net/browse/JDK-8249618) has been filed to normalize/clean up
usage of `@ignore` vs ProblemList.

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

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

From alanb at openjdk.java.net  Tue Jul 14 06:22:39 2020
From: alanb at openjdk.java.net (Alan Bateman)
Date: Tue, 14 Jul 2020 06:22:39 -0000
Subject: RFR: Filing bug, ProblemListing, Backing out [v6]
In-Reply-To: 
References: <6K28E8WDp4kNYhAs-o8jkcRFSzqdfSUqoeN92iXGgxM=.98bae31f-987a-40ca-988e-b2af5e1ff788@github.com>
 
 
Message-ID: 

On Fri, 10 Jul 2020 00:38:41 GMT, Igor Ignatyev  wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Put back Verify step in backout description.
>
> still LGTM

Filing a Bug - are you going to say anything about checking if the issue exists in the main line, esp. with
reproducible issues? Also what about advice on attaching a reproducer if possible?

"ProblemListing or `@ignore`-ing a Test".  The ProblemList.txt files are jtreg exclude list. Can this section be
renamed to "How to exclude tests"?  I don't think we've used "@ignore" for long time and might it simpler to just not
mention it.

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

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