From iris at sun.com Thu Feb 14 11:06:53 2008 From: iris at sun.com (Iris Clark) Date: Thu, 14 Feb 2008 11:06:53 -0800 (PST) Subject: The OpenJDK Developers' Guide - DRAFT version 0.01 Message-ID: <200802141906.m1EJ6ri0017094@ribbit.SFBay.Sun.COM> Welcome to the discussion of "The OpenJDK Developers' Guide"! http://openjdk.java.net/guide The Guide is intended to address the needs of developers who wish to participate in the future of the JDK. This mailing list is expected to be a place where we can discuss the Guide's content and delivery. See the "Introduction" for a description of the current content and our plans to evolve it. As we move forward, this section will be updated to describe the latest status. As always, feedback and comments are welcome. Thanks, iris From lars.westergren at gmail.com Sun Feb 17 23:53:16 2008 From: lars.westergren at gmail.com (Lars Westergren) Date: Mon, 18 Feb 2008 08:53:16 +0100 Subject: Suggested additions to "Testing" page Message-ID: <7cf9cdd90802172353wb86fe4cn16051f55ff95c40c@mail.gmail.com> Hello, Perhaps you are already working on this, but what I was missing the most when I was writing my little "contribution guide" was a mention that there are in fact a lot of tests included in OpenJDK when you do a Mercurial checkout. All the documentation I could find only talked about how to write your own jtreg tests, never where the existing tests could be found. Until there is a more complete page in place, perhaps you could just add the following to the page for those who are currently working on patches- "OpenJDK tests are located in the jdk/test directory. If for instance you have been changing code in the management package, you should at the minimum run the tests located in jdk/test/java/lang/management" Cheers, Lars From lars.westergren at gmail.com Mon Feb 18 09:29:37 2008 From: lars.westergren at gmail.com (Lars Westergren) Date: Mon, 18 Feb 2008 18:29:37 +0100 Subject: Mercurial book Message-ID: <7cf9cdd90802180929r603ead8ejc581687f6431c2e0@mail.gmail.com> In this chapter: http://openjdk.java.net/guide/repositories.html#installConfig Perhaps you could include a link to the free book about Mercurial? http://hgbook.red-bean.com/ Cheers, Lars From openjdk at jazillian.com Mon Feb 18 10:19:49 2008 From: openjdk at jazillian.com (Andy Tripp) Date: Mon, 18 Feb 2008 13:19:49 -0500 Subject: some thoughts about Change Planning page Message-ID: <47B9CC45.6020701@jazillian.com> I just found this guide - great idea! Here are some thoughts I had on this page: http://openjdk.java.net/guide/changePlanning.html * step 2, creating a bug, should go first * you mention "work with their sponsors" without saying what that means. * you mention a "CCC" without saying what it is. What does the acronym stand for and give me a link to find out more. * you mention "jtreg regression test" also. describe it and give a link. * in step 6 answer "N", an explanation is required *where*? in some field of the entry in the bug database? * why does step 8 require testing on just one OS, but step 9 on all? And do you really require that every change be tested on every platform by the developer making the change? That doesn't seem feasible. Andy -------------- next part -------------- An HTML attachment was scrubbed... URL: http://mail.openjdk.java.net/pipermail/guide-discuss/attachments/20080218/b628fa85/attachment.html From Kelly.Ohair at Sun.COM Tue Feb 19 10:36:17 2008 From: Kelly.Ohair at Sun.COM (Kelly O'Hair) Date: Tue, 19 Feb 2008 10:36:17 -0800 Subject: No talk about webrev Message-ID: <47BB21A1.5090001@sun.com> Is there no mention of webrev? I couldn't find anything. I'm just thinking we may want to at least refer to it. -kto From iris at sun.com Tue Feb 19 10:49:16 2008 From: iris at sun.com (iris clark) Date: Tue, 19 Feb 2008 10:49:16 -0800 (PST) Subject: Suggested additions to "Testing" page In-Reply-To: <7cf9cdd90802172353wb86fe4cn16051f55ff95c40c@mail.gmail.com> (message from Lars Westergren on Mon, 18 Feb 2008 08:53:16 +0100) Message-ID: <200802191849.m1JInG4q019138@ribbit.SFBay.Sun.COM> Hi, Lars. > Until there is a more complete page in place, perhaps you could just > add the following to the page for those who are currently working on > patches- > > "OpenJDK tests are located in the jdk/test directory. If for instance > you have been changing code in the management package, you should at > the minimum run the tests located in jdk/test/java/lang/management" Good idea. I'll see what I can do to beef up the "Testing Changes" [1] section in the next couple of days. I think that the sentence you provide above is a good start. The trick to writing about the regression test suite is to provide basic information without duplicating what's already been published in other parts of the site. For instance, natural variants to the "where are the tests located" question could be any of the following questions already answered in the jtreg FAQ: 2.9. What should I do with a test once I've written it? http://openjdk.java.net/jtreg/faq.html#question2.9 2.10. Where is the test directory? http://openjdk.java.net/jtreg/faq.html#question2.10 2.12. How are the test directories organized? http://openjdk.java.net/jtreg/faq.html#question2.12 2.13. What should I do if my test directory is missing a subdirectory that I need? http://openjdk.java.net/jtreg/faq.html#question2.13 2.14. How should I name a test? http://openjdk.java.net/jtreg/faq.html#question2.14 The right answer for the Guide is probably to provide a general reference to the jtreg FAQ and explicitly reference a few key questions. This allows the owners of the test suite to be the primary reference for all information about it. Thanks for the feedback! iris [1] http://openjdk.java.net/guide/testingChanges.html From iris at sun.com Tue Feb 19 11:10:05 2008 From: iris at sun.com (iris clark) Date: Tue, 19 Feb 2008 11:10:05 -0800 (PST) Subject: Mercurial book In-Reply-To: <7cf9cdd90802180929r603ead8ejc581687f6431c2e0@mail.gmail.com> (message from Lars Westergren on Mon, 18 Feb 2008 18:29:37 +0100) Message-ID: <200802191910.m1JJA5LG019154@ribbit.SFBay.Sun.COM> Hi, Lars. > In this chapter: > http://openjdk.java.net/guide/repositories.html#installConfig > > Perhaps you could include a link to the free book about Mercurial? > http://hgbook.red-bean.com/ An obvious improvement. No idea why I didn't do that when I wrote that section, perhaps because I'd already included a reference in the intro to the entire "Repositories" section? Regardless, the reference clearly needs to be added here too. I'll push this (and any other changes I've made) late this week or early next. Thanks, iris From Jonathan.Gibbons at Sun.COM Tue Feb 19 12:11:53 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Tue, 19 Feb 2008 12:11:53 -0800 Subject: Suggested additions to "Testing" page In-Reply-To: <200802191849.m1JInG4q019138@ribbit.SFBay.Sun.COM> References: <200802191849.m1JInG4q019138@ribbit.SFBay.Sun.COM> Message-ID: Note that not all the tests are in jdk/test. There are also tests in langtools/test. -- Jon On Feb 19, 2008, at 10:49 AM, iris clark wrote: > > Hi, Lars. > >> Until there is a more complete page in place, perhaps you could just >> add the following to the page for those who are currently working on >> patches- >> >> "OpenJDK tests are located in the jdk/test directory. If for instance >> you have been changing code in the management package, you should at >> the minimum run the tests located in jdk/test/java/lang/management" > > Good idea. I'll see what I can do to beef up the "Testing Changes" > [1] section in the next couple of days. > > I think that the sentence you provide above is a good start. The > trick to writing about the regression test suite is to provide basic > information without duplicating what's already been published in other > parts of the site. For instance, natural variants to the "where are > the tests located" question could be any of the following questions > already answered in the jtreg FAQ: > > 2.9. What should I do with a test once I've written it? > http://openjdk.java.net/jtreg/faq.html#question2.9 > > 2.10. Where is the test directory? > http://openjdk.java.net/jtreg/faq.html#question2.10 > > 2.12. How are the test directories organized? > http://openjdk.java.net/jtreg/faq.html#question2.12 > > 2.13. What should I do if my test directory is missing a > subdirectory that I need? > http://openjdk.java.net/jtreg/faq.html#question2.13 > > 2.14. How should I name a test? > http://openjdk.java.net/jtreg/faq.html#question2.14 > > The right answer for the Guide is probably to provide a general > reference to the jtreg FAQ and explicitly reference a few key > questions. This allows the owners of the test suite to be the primary > reference for all information about it. > > Thanks for the feedback! > iris > > [1] http://openjdk.java.net/guide/testingChanges.html From iris at sun.com Tue Feb 19 13:23:06 2008 From: iris at sun.com (iris clark) Date: Tue, 19 Feb 2008 13:23:06 -0800 (PST) Subject: some thoughts about Change Planning page In-Reply-To: <47B9CC45.6020701@jazillian.com> (message from Andy Tripp on Mon, 18 Feb 2008 13:19:49 -0500) Message-ID: <200802192123.m1JLN69R019248@ribbit.SFBay.Sun.COM> Hi, Andy. > I just found this guide - great idea! Thanks for the review comments. > Here are some thoughts I had on this page: > http://openjdk.java.net/guide/changePlanning.html > > * step 2, creating a bug, should go first I was optimizing for a different case, namely that most problems that have been reported turn out to be duplicates of existing bugs. Sometimes the fact that it's a duplicate doesn't become apparent until after discussion. This is particularly true for new features which may overlap work currently planned or in progress. The order in the Guide also describes the current process, but I don't consider this part of the sequence rigid. Submitting a bug first would allow for better tracking. We may consider changing this order if others provide similar feedback or if we determine that tracking of the initial discussions is difficult. > * you mention "work with their sponsors" without saying what that means. Yes, this is a hole. I don't think we've yet defined what the protocol should be for working with your sponsor. We all imagine it to be a fairly informal interaction but we don't yet know if it will be more common for the contributor to drive the change or the sponsor. For instance, is the contributor require to detail the changes which need to be applied to the bug when they need to occur or is that left to the discretion of the sponsor? Do we even want to define this? > * you mention a "CCC" without saying what it is. What does the acronym > stand for and > give me a link to find out more. I'm not quite sure what "CCC" stands for (and I'm on it :) ). In the back of my mind, I think it stands for "Committee for Concerned Citizens", but that could have been a punchline for a joke. Nevertheless, the CCC is ann important part of our current process. It is responsible for auditing anything that would change spec or externally visible behaviour in the JDK, such as adding a new API, tool option, or system property. The CCC is one of the "Process Tools" for interface review and change approval that Mark references in this blog: Upcoming OpenJDK infrastructure projects http://blogs.sun.com/mr/entry/under_construction I'll provide a definition of CCC and reference it in the Guide as appropriate. We'll need to keep in mind that the this review body's function (and possibly name) will likely change as as externalize its function. For this reason, we've been reluctant to provide much documentation about it. > * you mention "jtreg regression test" also. describe it and give a link. Good idea. > * in step 6 answer "N", an explanation is required *where*? in some > field of the entry > in the bug database? Historically we've advised that this information be added to the "Comments" section of the bug; however, since that's not a visible field, this should probably be revised to define some other publically-visible field. Off the top of my head, the "Evaluation" section sounds appropriate. I'll update this sentence to explicitly mention a section. > * why does step 8 require testing on just one OS, but step 9 on all? Here's the text for Step 8, "yes": Build and test on at least one instance of all three of the supported operating systems (Solaris, Linux, and Windows). Here's the text for Step 9, "yes": Build and test on all relevant platforms. Code under src/solaris builds on both Solaris and Linux, despite its name. I don't see an inconsistency here. Step 8 requires testing on at least three platforms. This has been a requirement for years. All of our build platforms are treated equally when group integrations occur, so if a change is supposed to apply to all platforms and a test reveals that it fails on one of them, then there's a general problem with the change which needs to be addressed. > And > do you really > require that every change be tested on every platform by the developer > making the change? > That doesn't seem feasible. We expect the person making the change to have some understanding of the potential risks of not testing everywhere. For example, historically we have discovered that changes in the launcher really need to be tested on all of the supported platforms because failure to do so will introduce severe regressions. If you fail to do sufficient testing, you run the risk of breaking the build which can be extremely disruptive. We understand that many contributors don't have ready access to build/test machines on all the supported platforms. One of the sponsor's reponsibilities is to ensure that the appropriate tests have been run. The sponsor does have access to machines for all of the build platforms and can assist contributors in validating their changes. This can be a heavy burden on sponsors, but until we provide a distributed build/test system (as described in Mark's blog), we have no other choice. Note that some groups, such as the Hotspot Team are very strict about comprehensive platform testing and have a system to require testing on all changes as part of the commit process. Changes which are committed but fail testing on any platform will never make it into one of their repositories. I think this all comes back to the fact that sponsorship has not been defined. Thanks, iris From Bradford.Wetmore at Sun.COM Thu Feb 21 18:36:11 2008 From: Bradford.Wetmore at Sun.COM (Brad Wetmore) Date: Thu, 21 Feb 2008 18:36:11 -0800 Subject: The OpenJDK Developers' Guide - DRAFT version 0.01 In-Reply-To: <200802141847.m1EIljjO016999@ribbit.SFBay.Sun.COM> References: <200802141847.m1EIljjO016999@ribbit.SFBay.Sun.COM> Message-ID: <47BE351B.80808@sun.com> Hi Iris, Iris Clark wrote: > I am pleased to announce that DRAFT version 0.01 of "The OpenJDK > Developers' Guide" is now available at http://openjdk.java.net/guide. Nice job culling down a lot of info. > A > mailing list, guide-discuss at openjdk.java.net, has been created for > discussion. Incidentally/personally, I tend to agree with folks regarding the overabundance of email aliases at Sun. It's so easy to come to a project late, and you have no idea what aliases you *should* or *supposed* to be be on, meanwhile you're missing relevant discussions. Fortunately, they are archived. Anyway, to specifics: http://openjdk.java.net/guide/ I'd suggest putting an intro para here, just to say this is still under development, not complete, etc. (or copying/moving that para from the intro page.) http://openjdk.java.net/guide/intro.html > "Comments may be sent to..." Suggest you also include a link to the guide-discuss archives: http://mail.openjdk.java.net/pipermail/guide-discuss/ so people can see the back issues. > First, production of this document needs to be part of an OpenJDK > project. Isn't the o.j.n hierarchy going to move to a mercurial repository soon? If so, would that be a good place for it? Or are you thinking of a separate repository just for this guide? > 2007/Q4 As it's now 2008/Q1, do you want to shift these dates by a quarter so people don't have unreasonable expectations? http://openjdk.java.net/guide/repositories.html > "The JDK source is available from other locations, for example src.zip > from a full JDK distribution." That is only partial source, so you should mention that in your later. Actually, I think you might want to open with the sentence "Portions of the JDK source are available..." and "OpenJDK contributions must use source from the OpenJDK Mercurial repositories..." >

This is probably outside your realm, but the current CSS style sheets don't really make an obvious distinction between the level header format. I was hoping for at least a font size change to help me note the different parts of the hierarchy, not just an italics change. > The promoted builds are performed using the source in the MASTER > forest of repositories The term MASTER was obvious when we had repositories called MASTER, but since they're now called jdk7, maybe you should add a note here showing where the MASTERS are for jdk7. > Repositories may be either read-only or read/write. Clones are made > from read-only repositories. Changeset pushes are made into the > read/write repositories, which are called gate repositories. A picture's worth a thousand words. MASTER (R/O)<-------MASTER-gate (R/W) | ^ | | +---->dev workspace----+ > The repositories use following naming scheme: > > /{-gate}?/ Really suggest adding an example here: jdk7/JSN/jdk jdk7/TL-gate/langtools > Contact Mailing Lists In addition to the mailto, maybe having a link to the archives? > build (also know as Release Engineering or RE) also know*n* as. Missing n. > hotspot-comp Hotspot Compiler implementation as provided by members > of the Hotspot group I'm not parsing what this is supposed to be. Does this mean hotspot-{comp,gc,rt,svc} all feed into this forest? > jsn Security and Networking APIs and implementations as provided by JSN does not include the original NIO, which are part of TL. You might want to call this out. > Components > > The following table describes the components (or trees) in each forest > of repositories. You should also mention the top level (previously known as control). Newbies might not appreciate that it is yet another repository. > http://www.selenic.com/mercurial/wiki/index.cgi. Suggest using: http://www.selenic.com/mercurial/wiki/ Also note, extra period at the end of the text that might be confusing to readers not using hyperlinks. (i.e. those that print out this guide and enter the URL by hand.) This will give a 404. Same comment about the period for the other links: http://www.selenic.com/mercurial/wiki/index.cgi/UnixInstall. http://www.selenic.com/mercurial/wiki/index.cgi/ForestExtension. > Solaris: We can talk about the following offline if you like, but working in mercurial under windows is *NOT* a straightforward process and should have a section of it's own. You should talk about the windows gotchas, mainly that windows puts in ^M's at the end of lines, and they won't be allowed by jcheck. (need to use dos2unix (solaris), flip (MKS), or something similiar (tr/sed/perl/etc)) Also, the default windows Mercurial distributions don't include a hgmerge file. You have to create one. And if it's a bourne shell merge script, it needs to be named hgmerge.sh, otherwise, it assumes a MSDOS script. > Create and edit the ~/.hgrc file to minimally contain the following > entries: If you're going to be mentioning fetch here, you should probably add: [defaults] fetch = -m Merge and also put in a mention for the eventual jcheck and its hooks. > jdk_username is a plain lowercase, You need to have a section where you talk about how openjdk usernames are created/used, and then you need to link from here to there. > $ hg help > full output Either the abbreviated output should be moved here, or you need to say something like "" > Cloning... Suggest reversing the order of single and forest. Let them know there is a repository they can clone, then that forest can be used to simplify things... Also, can they push to the sandbox? We haven't really talked about pushes yet. http://openjdk.java.net/guide/codeConventions.html Suggest you at least mention the major expected changes such as whitespace. http://openjdk.java.net/guide/changePlanning.html > are urged to work with their sponsors Iris wrote: > I don't think we've yet defined what the > protocol should be for working with your sponsor. Since sponsors haven't been defined yet, you should probably at least have a link to http://openjdk.java.net/contribute/ > CCC/SDN/jdcinclude/etc. Looks like Andy Tripp had the same comment. Lots of these terms have not been described yet, so it's not clear what's involved. Yes, these sections are TBD, but you might want to at least give a 2 second description here so people aren't scratching their heads as to what CCC is/does, or else fill in that part in the glossary now. > I'm not quite sure what "CCC" stands for I've heard Committee of Concerned Citizens, Change Consideration Committee, and the Committee of Cranky Curmudgeons. Ok, I made that last one up... ;) > For bugs, provide a jtreg regression test Provide a link to jtreg. > -hard You should say that you should at least try to come up with a race case, not just simply use noreg-hard because you're not sure if it can be dup'd. I've written several relatively easy race cases that were originally marked noreg-hard. > 10. Run relevant regression and unit tests on all relevant platforms to which Lars Westergren wrote: > Until there is a more complete page in place, perhaps you could just > add the following to the page for those who are currently working on > patches- > > "OpenJDK tests are located in the jdk/test directory. If for instance > you have been changing code in the management package, you should at > the minimum run the tests located in jdk/test/java/lang/management" and Jon wrote: > Note that not all the tests are in jdk/test. There are also tests in > langtools/test. and hotspot/test. I strongly suggest adding a note here to check with your gatekeeper and/or project group to determine which tests to run. http://openjdk.java.net/guide/producingChangeset.html > Setting a JDK User Name Same comment about how to obtain an OpenJDK User name. You might want to point a bit earlier to "Installing and Configuring Mercurial" instead of "Verifying the Configuration", so in case the users haven't already set their username, they will know how and what it should look like when properly configured. > ... Nowhere is jcheck mentioned here. It needs to be clear that there will be restrictions on content in both the changeset description and the files themselves, and that jcheck will be enforcing that at both the local and repository level. It's fine to say "jcheck is under development." > The timing for creating a changeset is important. I'd suggest simply advising that changesets should only be created after review, and just before checkin. With the way jcheck is currently set to operate, you can only use a bugid once in a repository. Any changes either have to be backed out completely before an integration, or else a new bugid has to be created. > They are therefore identified by their OpenJDK usernames rather than > full e-mail addresses. This is an aside, but how do we figure out the username->user->email mapping? > If a changeset contains multiple unrelated changes (this is frowned > upon, but may happen from time to time) then its comment will contain > multiple blocks of the above form, separated by blank lines. Blank lines are not allowed anywhere in a changeset comment, at least in Mark's current jcheck. > The required format of the comments will be enforced whenever the > changeset is pushed into the JDK 6/7 This is the only place you mention JDK 6/7 by name. Since OpenJDK6 is still under teamware for a while longer, maybe you want to keep this generic to OpenJDK? > Option 1: hg fpull I'd suggest "hg fpull; hg fupdate" > At this point, there are no recommendations for the format of the > merge comment. Currently it's "Merge" in jcheck. > Actual file merging will be done with the selected Mercurial merging > tool see MergeProgram for the details on how to define the selected > merge tool in ~/.hgrc. Shouldn't we get into silent/automatic/fuzzy merges here? > For MASTER repositories, the integrators and members of the Release > Engineering Team can push. I think the term "gatekeepers" should be used here instead of "integrators". IMHO, integrators is too generic a term, and means anyone who integrates code into a repository, and can be hard to explain to outside folks. A gatekeeper, by contrast, is a different type of person who controls access to the MASTERs. I would also suggest adding a note somewhere about how code goes from the project gates to the MASTERs. (i.e. gatekeepers). If you haven't seen it already: http://blogs.sun.com/wetmore/entry/you_re_a_gatekeeper_uh http://openjdk.java.net/guide/glossary.html I'd suggest pulling in parts of Kelly's Glossary here. http://wikis.sun.com/display/OpenJdkBuilds/JDK+Glossary+of+Terms HTH, Brad From Jean-Francois.Denise at Sun.COM Tue Feb 26 03:18:33 2008 From: Jean-Francois.Denise at Sun.COM (Jean-Francois Denise) Date: Tue, 26 Feb 2008 12:18:33 +0100 Subject: Feedbacks on the OpenJDK guide. Message-ID: <47C3F589.2080004@Sun.COM> Hello, 2 feedbacks that should help better understand the projects structure and naming. File : http://openjdk.java.net/guide/repositories.html Chapter : Projects Feedback : Re-stating at the beginning of this chapter that a project is a forest would help differentiate between the associations Project => Forest and Component => Repository File : http://openjdk.java.net/guide/repositories.html Chapter : Components Feedback : I would write : "The following table describes the components (or trees) in projects (or forests)." Jean-Francois -- Jean-Francois Denise JMX team Interested in netbeans ==> http://blogs.sun.com/roller/page/jmxnetbeans