From David.Herron at Sun.COM Mon Mar 3 17:21:39 2008 From: David.Herron at Sun.COM (David Herron) Date: Mon, 03 Mar 2008 17:21:39 -0800 Subject: Per-component repositories Message-ID: <47CCA423.5090806@sun.com> The discussion about per-component repositories [1] doesn't seem to match reality. If one wanted to check out just one component-area workspace it's not clear how to proceed from the guidebook description. It says the URL pattern is: /{-gate}?/ obviously is 'jdk7' ... but then precisely what value is used for '' and '' The page lists project names such as '2d' so perhaps one of these would work hg clone http://hg.openjdk.java.net/jdk7/2d hg clone http://hg.openjdk.java.net/jdk7/jdk7/2d But those result in a directory containing just the license & README & make files, and no source. On the other hand this following results in just the CORBA repository being checked out hg clone http://hg.openjdk.java.net/jdk7/jdk7/corba - David Herron [1] http://openjdk.java.net/guide/repositories.html#term From Kelly.Ohair at Sun.COM Mon Mar 3 18:44:05 2008 From: Kelly.Ohair at Sun.COM (Kelly O'Hair) Date: Mon, 03 Mar 2008 18:44:05 -0800 Subject: Per-component repositories In-Reply-To: <47CCA423.5090806@sun.com> References: <47CCA423.5090806@sun.com> Message-ID: <47CCB775.4070804@sun.com> These are forests, use fclone rather than clone, and the first time you need to make sure the destination does not exist, e.g. rm -f -r my2d hg fclone http://hg.openjdk.java.net/jdk7/2d my2d -kto David Herron wrote: > The discussion about per-component repositories [1] doesn't seem to > match reality. > > If one wanted to check out just one component-area workspace it's not > clear how to proceed from the guidebook description. > > It says the URL pattern is: /{-gate}?/ > > obviously is 'jdk7' ... but then precisely what value is used > for '' and '' > > The page lists project names such as '2d' so perhaps one of these would work > > hg clone http://hg.openjdk.java.net/jdk7/2d > hg clone http://hg.openjdk.java.net/jdk7/jdk7/2d > > But those result in a directory containing just the license & README & > make files, and no source. > > On the other hand this following results in just the CORBA repository > being checked out > > hg clone http://hg.openjdk.java.net/jdk7/jdk7/corba > > - David Herron > > > > [1] http://openjdk.java.net/guide/repositories.html#term > _______________________________________________ > guide-discuss mailing list > guide-discuss at openjdk.java.net > http://mail.openjdk.java.net/mailman/listinfo/guide-discuss From Jonathan.Gibbons at Sun.COM Wed Mar 5 07:51:17 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Wed, 05 Mar 2008 07:51:17 -0800 Subject: summary page for process workflow? Message-ID: The Guide currently has the potential for a lot of detail about the process workflow, spread over many pages. It would also be nice to have a shorter summary "checklist" page, particularly for all the steps to get code back into a repository once you have prepared the new code. There's a lot of steps there: test, get approvals (CCC, Core), review, fix white space, create putback message, update repository (i.e. pull), create changeset, deal with conflicts, and finally, push. Phew. -- Jon From David.Herron at Sun.COM Wed Mar 5 08:49:38 2008 From: David.Herron at Sun.COM (David Herron) Date: Wed, 05 Mar 2008 08:49:38 -0800 Subject: Per-component repositories In-Reply-To: <47CCB775.4070804@sun.com> References: <47CCA423.5090806@sun.com> <47CCB775.4070804@sun.com> Message-ID: <47CECF22.9060203@sun.com> Hi Kelly, thank you, and I also found the same thing described on the internal page you set up. I'm thinking right now my original question probably doesn't have a strong use-case-justification. Is there any reason to check out just one of the repositories? (just one tree rather than the whole forest) However there is the issue of the individual team repositories. Is there a way to discover the full set of repositories we're hosting on openjdk.java.net?? And also the parent/child relationships between those repositories? (This might be OT for discussion in the guide) - David Kelly O'Hair wrote: > > These are forests, use fclone rather than clone, and the first time > you need to make sure the destination does not exist, e.g. > > rm -f -r my2d > hg fclone http://hg.openjdk.java.net/jdk7/2d my2d > > -kto > > David Herron wrote: >> The discussion about per-component repositories [1] doesn't seem to >> match reality. >> >> If one wanted to check out just one component-area workspace it's not >> clear how to proceed from the guidebook description. >> It says the URL pattern is: /{-gate}?/ >> >> obviously is 'jdk7' ... but then precisely what value is >> used for '' and '' >> >> The page lists project names such as '2d' so perhaps one of these >> would work >> >> hg clone http://hg.openjdk.java.net/jdk7/2d >> hg clone http://hg.openjdk.java.net/jdk7/jdk7/2d >> >> But those result in a directory containing just the license & README >> & make files, and no source. >> >> On the other hand this following results in just the CORBA repository >> being checked out >> >> hg clone http://hg.openjdk.java.net/jdk7/jdk7/corba >> >> - David Herron >> >> >> >> [1] http://openjdk.java.net/guide/repositories.html#term >> _______________________________________________ >> guide-discuss mailing list >> guide-discuss at openjdk.java.net >> http://mail.openjdk.java.net/mailman/listinfo/guide-discuss From Jonathan.Gibbons at Sun.COM Wed Mar 5 09:02:36 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Wed, 05 Mar 2008 09:02:36 -0800 Subject: Per-component repositories In-Reply-To: <47CECF22.9060203@sun.com> References: <47CCA423.5090806@sun.com> <47CCB775.4070804@sun.com> <47CECF22.9060203@sun.com> Message-ID: <11E26941-C9C8-4A0D-9C4D-8AB2A78AEC9A@sun.com> David, I routinely check out just the langtools repository for working on the compiler. Since the build is set up to import "missing" bits, I would expect that most folk would just check out the repository they're actually working on. -- Jon On Mar 5, 2008, at 8:49 AM, David Herron wrote: > Hi Kelly, thank you, and I also found the same thing described on the > internal page you set up. > > I'm thinking right now my original question probably doesn't have a > strong use-case-justification. Is there any reason to check out just > one of the repositories? (just one tree rather than the whole forest) > > However there is the issue of the individual team repositories. Is > there a way to discover the full set of repositories we're hosting on > openjdk.java.net?? And also the parent/child relationships between > those repositories? > > (This might be OT for discussion in the guide) > > - David > > > > Kelly O'Hair wrote: >> >> These are forests, use fclone rather than clone, and the first time >> you need to make sure the destination does not exist, e.g. >> >> rm -f -r my2d >> hg fclone http://hg.openjdk.java.net/jdk7/2d my2d >> >> -kto >> >> David Herron wrote: >>> The discussion about per-component repositories [1] doesn't seem to >>> match reality. >>> >>> If one wanted to check out just one component-area workspace it's >>> not >>> clear how to proceed from the guidebook description. >>> It says the URL pattern is: /{-gate}?/ >>> >>> obviously is 'jdk7' ... but then precisely what value is >>> used for '' and '' >>> >>> The page lists project names such as '2d' so perhaps one of these >>> would work >>> >>> hg clone http://hg.openjdk.java.net/jdk7/2d >>> hg clone http://hg.openjdk.java.net/jdk7/jdk7/2d >>> >>> But those result in a directory containing just the license & README >>> & make files, and no source. >>> >>> On the other hand this following results in just the CORBA >>> repository >>> being checked out >>> >>> hg clone http://hg.openjdk.java.net/jdk7/jdk7/corba >>> >>> - David Herron >>> >>> >>> >>> [1] http://openjdk.java.net/guide/repositories.html#term >>> _______________________________________________ >>> guide-discuss mailing list >>> guide-discuss at openjdk.java.net >>> http://mail.openjdk.java.net/mailman/listinfo/guide-discuss > _______________________________________________ > guide-discuss mailing list > guide-discuss at openjdk.java.net > http://mail.openjdk.java.net/mailman/listinfo/guide-discuss From Kelly.Ohair at Sun.COM Wed Mar 5 09:04:35 2008 From: Kelly.Ohair at Sun.COM (Kelly O'Hair) Date: Wed, 05 Mar 2008 09:04:35 -0800 Subject: summary page for process workflow? In-Reply-To: References: Message-ID: <47CED2A3.2040501@sun.com> I agree. I'd also like to see a way to get it all in one html page so I could potentially print it. Call me old-fashioned. ;^) I'll use recycled paper. -kto Jonathan Gibbons wrote: > The Guide currently has the potential for a lot of detail about the > process workflow, spread over many pages. It would also be nice to > have a shorter summary "checklist" page, particularly for all the > steps to get code back into a repository once you have prepared the > new code. There's a lot of steps there: test, get approvals (CCC, > Core), review, fix white space, create putback message, update > repository (i.e. pull), create changeset, deal with conflicts, and > finally, push. Phew. > > -- Jon > _______________________________________________ > guide-discuss mailing list > guide-discuss at openjdk.java.net > http://mail.openjdk.java.net/mailman/listinfo/guide-discuss From Jonathan.Gibbons at Sun.COM Wed Mar 5 09:08:54 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Wed, 05 Mar 2008 09:08:54 -0800 Subject: summary page for process workflow? In-Reply-To: <47CED2A3.2040501@sun.com> References: <47CED2A3.2040501@sun.com> Message-ID: <7165331D-1B42-4F02-B9D8-5F3898CCD5F9@Sun.COM> There is a utility I wrote back in my JavaTest days called "htmljoin" that could join a set of HTML files into a single file, adjusting header levels, cross-references, and other fixups as needed. We used it to convert the online help files for JavaTest into a single document that could be printed. Perhaps we could use something like that to create the big one-page version. -- Jon On Mar 5, 2008, at 9:04 AM, Kelly O'Hair wrote: > I agree. > > I'd also like to see a way to get it all in one html page so I could > potentially print it. Call me old-fashioned. ;^) I'll use recycled > paper. > > -kto > > Jonathan Gibbons wrote: >> The Guide currently has the potential for a lot of detail about >> the process workflow, spread over many pages. It would also be >> nice to have a shorter summary "checklist" page, particularly for >> all the steps to get code back into a repository once you have >> prepared the new code. There's a lot of steps there: test, get >> approvals (CCC, Core), review, fix white space, create putback >> message, update repository (i.e. pull), create changeset, deal >> with conflicts, and finally, push. Phew. >> -- Jon >> _______________________________________________ >> guide-discuss mailing list >> guide-discuss at openjdk.java.net >> http://mail.openjdk.java.net/mailman/listinfo/guide-discuss From Kelly.Ohair at Sun.COM Wed Mar 5 09:49:38 2008 From: Kelly.Ohair at Sun.COM (Kelly O'Hair) Date: Wed, 05 Mar 2008 09:49:38 -0800 Subject: Per-component repositories In-Reply-To: <47CECF22.9060203@sun.com> References: <47CCA423.5090806@sun.com> <47CCB775.4070804@sun.com> <47CECF22.9060203@sun.com> Message-ID: <47CEDD32.7080100@sun.com> David Herron wrote: > Hi Kelly, thank you, and I also found the same thing described on the > internal page you set up. > > I'm thinking right now my original question probably doesn't have a > strong use-case-justification. Is there any reason to check out just > one of the repositories? (just one tree rather than the whole forest) Yes, in some cases, there may be a valid reason to just get one repository or a partial forest. A developer may wish to focus on certain repositories and ignore the rest until it's time to push the changes. It depends on what the team considered acceptable practice. For example, the hotspot team does almost all there work without ever building a jdk themselves. They have the ability to isolate their work and test it using a promoted jdk image. All repositories (except for the enclosing repository) is independently buildable and can be worked on by developers independently. > > However there is the issue of the individual team repositories. Is > there a way to discover the full set of repositories we're hosting on > openjdk.java.net?? And also the parent/child relationships between > those repositories? There are multiple dimensions here. The basic OpenJDK forest contains 7 unique repositories, an enclosing repository plus corba, hotspot, jaxp, jaxws, jdk, and langtools. Every repository is represented as a pair, the pull (http) repository and the push (ssh) "-gate" repository. So each forest is actually implemented with 14 (7*2) repositories. The master area is jdk7/jdk7 and it's child team areas are: jdk7/2d jdk7/awt jdk7/build jdk7/corba jdk7/hotspot (has children: jdk7/hotspot-comp, jdk7/hotspot-gc, jdk7/hotspot-rt, jdk7/hotspot-svc) jdk7/i18n jdk7/jaxp jdk7/jaxws jdk7/jsn (may be a child of jdk7/tl?) jdk7/l10n jdk7/modules (may be a child of jdk7/tl? Or special project?) jdk7/nio2 (may be a child of jdk7/tl? Or special project?) jdk7/swing jdk7/tl The jdk7/modules and jdk7/nio2 may be considered "projects" and may or may not push directly to the master area. I'm not sure about those, the team gets to decide. A project may create many changesets that could at project completion get folded together into fewer official changesets that get pushed into the master area eventually. It depends on the team and the project. We are trying to be flexible but at the same time make sure the changesets that get integrated follow the rules we have setup. -kto > > (This might be OT for discussion in the guide) > > - David > > > > Kelly O'Hair wrote: >> These are forests, use fclone rather than clone, and the first time >> you need to make sure the destination does not exist, e.g. >> >> rm -f -r my2d >> hg fclone http://hg.openjdk.java.net/jdk7/2d my2d >> >> -kto >> >> David Herron wrote: >>> The discussion about per-component repositories [1] doesn't seem to >>> match reality. >>> >>> If one wanted to check out just one component-area workspace it's not >>> clear how to proceed from the guidebook description. >>> It says the URL pattern is: /{-gate}?/ >>> >>> obviously is 'jdk7' ... but then precisely what value is >>> used for '' and '' >>> >>> The page lists project names such as '2d' so perhaps one of these >>> would work >>> >>> hg clone http://hg.openjdk.java.net/jdk7/2d >>> hg clone http://hg.openjdk.java.net/jdk7/jdk7/2d >>> >>> But those result in a directory containing just the license & README >>> & make files, and no source. >>> >>> On the other hand this following results in just the CORBA repository >>> being checked out >>> >>> hg clone http://hg.openjdk.java.net/jdk7/jdk7/corba >>> >>> - David Herron >>> >>> >>> >>> [1] http://openjdk.java.net/guide/repositories.html#term >>> _______________________________________________ >>> guide-discuss mailing list >>> guide-discuss at openjdk.java.net >>> http://mail.openjdk.java.net/mailman/listinfo/guide-discuss > _______________________________________________ > guide-discuss mailing list > guide-discuss at openjdk.java.net > http://mail.openjdk.java.net/mailman/listinfo/guide-discuss From iris at sun.com Wed Mar 5 12:50:46 2008 From: iris at sun.com (iris clark) Date: Wed, 5 Mar 2008 12:50:46 -0800 (PST) Subject: summary page for process workflow? In-Reply-To: (message from Jonathan Gibbons on Wed, 05 Mar 2008 07:51:17 -0800) Message-ID: <200803052050.m25Kokh4028266@ribbit.SFBay.Sun.COM> Hi, Jon. > The Guide currently has the potential for a lot of detail about the > process workflow, spread over many pages. It would also be nice to > have a shorter summary "checklist" page, particularly for all the > steps to get code back into a repository once you have prepared the > new code. There's a lot of steps there: test, get approvals (CCC, > Core), review, fix white space, create putback message, update > repository (i.e. pull), create changeset, deal with conflicts, and > finally, push. Phew. Fantastic idea! As you say, there's quite a bit of text and I don't expect that people are going to want to read it often. I was hoping that the "Process Workflow" section [TBD] with associated diagrams would address most of this problem: http://openjdk.java.net/guide/processWorkflow.html But also I really like the idea of having up-to-date checklist(s?) which reference the more detailed portions of the guide as necessary. I could also see some kind of "Quick Reference Guide". Do you have an initial list we can start with? From your message, I'm seeing something like this: - test - get approvals (CCC, Core) - review - fix white space - create putback message - update repository (i.e. pull) - create changeset - deal with conflicts, - push I know that they don't exist yet, but is this checklist just another representation for the Process Workflow diagrams? Thanks, iris From iris at sun.com Wed Mar 5 12:54:35 2008 From: iris at sun.com (Iris Garcia) Date: Wed, 5 Mar 2008 12:54:35 -0800 (PST) Subject: Per-component repositories In-Reply-To: <47CECF22.9060203@sun.com> (message from David Herron on Wed, 05 Mar 2008 08:49:38 -0800) Message-ID: <200803052054.m25KsZRK028272@ribbit.SFBay.Sun.COM> Hi, David. > Is there any reason to check out just > one of the repositories? (just one tree rather than the whole forest) I debatted about that one for a while. Given the way that various portions of the build system currently works (for instance, it is difficult to get a javadoc build if you only have a single repository in the forest), in my mind developers should operate on forests by default... hence this comment in "Respositories: Cloning": http://openjdk.java.net/guide/repositories.html#clone It is strongly recommended for developers to clone the entire project's forest, rather than a single repository. This is the only means to ensure consistency in builds. The follow example illustrates how to clone the entire tl forest into the directory mytl. Here's what the Guide says about retrieving only a single repository in the forest: If reading a limited portion of the source is the only goal, it is possible to clone a single repository from a project forest. For instance, this example shows how to clone the langtools repository from the tl project into the default destination directory. Since I've always had partial repositories in the old "CodeManager" system (sometimes consisting of only a single file or small directory), I can see many other uses of a single repository. In fact, I'm going to guess that large portions of developers are going to care about only a single part of the repository. For instance, jaxws developers will probably largely operate on the jaxws tree, so the other trees may not be interesting. Similar comments can probably be made for hotspot and language developers. My guess is for this approach to be successful, the developer needs to be very comfortable with the build structure and any potential side-effects their modifications may cause. For instance, as a developer in Core Libraries, it would seem that I only need to retrieve the "jdk" portion of the repository since that's where the implementation of those classes resides. However, I would need to be pretty confident to not do a full build of the entire forest before I did my commit. Even if I was only modifying javadoc, I'd still need the forest for a full javadoc build. > However there is the issue of the individual team repositories. Is > there a way to discover the full set of repositories we're hosting on > openjdk.java.net?? Yes, from the Guide, "Terminology and Naming Scheme": The OpenJDK repository forests are located at http://hg.openjdk.java.net/. > And also the parent/child relationships between > those repositories? I haven't verified the diagram for this, but I believe that the relationship is similar to what we've had historically and it's something like this: - MASTER - 2d - awt - build - corba - hotspot - hotspot-comp - hotspot-gc - hotspot-rt - hotspot-svc - i18n - jaxp - jaxws - l10n - tl - jsn - modules - swing I'm not sure where "nio2" goes since it's not in use. Logical candiates are directly to the MASTER and to tl. I'm also not certain how the serviceability and JMX teams will be handling their putbacks. I think they're going back directly into TL, but I'd need to check the commit logs to verify. Thanks, iris From Jonathan.Gibbons at Sun.COM Wed Mar 5 14:03:48 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Wed, 05 Mar 2008 14:03:48 -0800 Subject: Per-component repositories In-Reply-To: <200803052054.m25KsZRK028272@ribbit.SFBay.Sun.COM> References: <200803052054.m25KsZRK028272@ribbit.SFBay.Sun.COM> Message-ID: <47CF18C4.9010203@sun.com> Iris, As I said earlier, it is common to work on langtools in isolation. The primary tests for the compiler are the regression tests in the same workspace, and JCK, which is separate. The build system is primarily Ant, and NetBeans friendly, with Makefile wrappers, as compared to the Makefiles and ant/NetBeans wrappers in, say, the jdk repository. My understanding is that the new EE repositories (jaxp, corba, etc) are more similar to langtools than jdk, in that respect. I agree that doing a full build is often useful, but to me, it makes more sense to have a single forest in which I can "install" my repository and do a build there, when needed, rather than to have every work area be a complete forest. -- Jon Iris Garcia wrote: > Hi, David. > > >> Is there any reason to check out just >> one of the repositories? (just one tree rather than the whole forest) >> > > I debatted about that one for a while. Given the way that various portions of > the build system currently works (for instance, it is difficult to get a > javadoc build if you only have a single repository in the forest), in my mind > developers should operate on forests by default... hence this comment in > "Respositories: Cloning": > > http://openjdk.java.net/guide/repositories.html#clone > > It is strongly recommended for developers to clone the entire > project's forest, rather than a single repository. This is the only > means to ensure consistency in builds. The follow example illustrates > how to clone the entire tl forest into the directory mytl. > > Here's what the Guide says about retrieving only a single repository in the > forest: > > If reading a limited portion of the source is the only goal, it is > possible to clone a single repository from a project forest. For > instance, this example shows how to clone the langtools repository > from the tl project into the default destination directory. > > Since I've always had partial repositories in the old "CodeManager" system > (sometimes consisting of only a single file or small directory), I can see many > other uses of a single repository. In fact, I'm going to guess that large > portions of developers are going to care about only a single part of the > repository. For instance, jaxws developers will probably largely operate on > the jaxws tree, so the other trees may not be interesting. Similar comments > can probably be made for hotspot and language developers. My guess is for this > approach to be successful, the developer needs to be very comfortable with the > build structure and any potential side-effects their modifications may cause. > For instance, as a developer in Core Libraries, it would seem that I only need > to retrieve the "jdk" portion of the repository since that's where the > implementation of those classes resides. However, I would need to be pretty > confident to not do a full build of the entire forest before I did my commit. > Even if I was only modifying javadoc, I'd still need the forest for a full > javadoc build. > > >> However there is the issue of the individual team repositories. Is >> there a way to discover the full set of repositories we're hosting on >> openjdk.java.net?? >> > > Yes, from the Guide, "Terminology and Naming Scheme": > > The OpenJDK repository forests are located at http://hg.openjdk.java.net/. > > >> And also the parent/child relationships between >> those repositories? >> > > I haven't verified the diagram for this, but I believe that the relationship is > similar to what we've had historically and it's something like this: > > - MASTER > - 2d > - awt > - build > - corba > - hotspot > - hotspot-comp > - hotspot-gc > - hotspot-rt > - hotspot-svc > - i18n > - jaxp > - jaxws > - l10n > - tl > - jsn > - modules > - swing > > I'm not sure where "nio2" goes since it's not in use. Logical candiates are > directly to the MASTER and to tl. I'm also not certain how the serviceability > and JMX teams will be handling their putbacks. I think they're going back > directly into TL, but I'd need to check the commit logs to verify. > > Thanks, > iris > > > _______________________________________________ > guide-discuss mailing list > guide-discuss at openjdk.java.net > http://mail.openjdk.java.net/mailman/listinfo/guide-discuss > -------------- next part -------------- An HTML attachment was scrubbed... URL: http://mail.openjdk.java.net/pipermail/guide-discuss/attachments/20080305/9e4fb4f9/attachment.html From Jonathan.Gibbons at Sun.COM Wed Mar 5 14:12:31 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Wed, 05 Mar 2008 14:12:31 -0800 Subject: summary page for process workflow? In-Reply-To: <200803052050.m25Kokh4028266@ribbit.SFBay.Sun.COM> References: <200803052050.m25Kokh4028266@ribbit.SFBay.Sun.COM> Message-ID: <47CF1ACF.2010708@sun.com> A workflow diagram sounds useful but different. It's good detail for the person trying to navigate through the process, to figure out what to do next when something goes wrong. For my part, a quick reference guide is useful, more details than a flow chart, but less detailed than multiple pages of info. I've been developing one for myself and other compiler folk. Having it be hyperlinked into more detailed pages would be good. I'll attach the one I've been using for myself, as an example. Obviously, this one is specific to the compiler team, but you get the idea. -- Jon iris clark wrote: > Hi, Jon. > > >> The Guide currently has the potential for a lot of detail about the >> process workflow, spread over many pages. It would also be nice to >> have a shorter summary "checklist" page, particularly for all the >> steps to get code back into a repository once you have prepared the >> new code. There's a lot of steps there: test, get approvals (CCC, >> Core), review, fix white space, create putback message, update >> repository (i.e. pull), create changeset, deal with conflicts, and >> finally, push. Phew. >> > > Fantastic idea! As you say, there's quite a bit of text and I don't > expect that people are going to want to read it often. I was hoping > that the "Process Workflow" section [TBD] with associated diagrams > would address most of this problem: > > http://openjdk.java.net/guide/processWorkflow.html > > But also I really like the idea of having up-to-date checklist(s?) > which reference the more detailed portions of the guide as necessary. > I could also see some kind of "Quick Reference Guide". > > Do you have an initial list we can start with? From your message, I'm > seeing something like this: > > - test > - get approvals (CCC, Core) > - review > - fix white space > - create putback message > - update repository (i.e. pull) > - create changeset > - deal with conflicts, > - push > > I know that they don't exist yet, but is this checklist just another > representation for the Process Workflow diagrams? > > Thanks, > iris > -------------- next part -------------- An HTML attachment was scrubbed... URL: http://mail.openjdk.java.net/pipermail/guide-discuss/attachments/20080305/1c9cb727/attachment.html -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: jdk-check.txt Url: http://mail.openjdk.java.net/pipermail/guide-discuss/attachments/20080305/1c9cb727/attachment.txt From Jonathan.Gibbons at Sun.COM Thu Mar 6 10:18:36 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Thu, 06 Mar 2008 10:18:36 -0800 Subject: errata for Contributed-by Message-ID: <47D0357C.7060309@sun.com> http://openjdk.java.net/guide/producingChangeset.html#create lists this example for a changeset message: 1234567: NPE thrown on FileInputStream("") Summary: Rewrite precondition-checking code in io.c Reviewed-by: mr Contributed-by: Ben Bitdiddle In practice, it seems jcheck requires a real email address. At any rate, it gave me an unspecific "invalid contributor attribution" when I tried to follow the example. From mr at sun.com Thu Mar 6 10:57:15 2008 From: mr at sun.com (Mark Reinhold) Date: Thu, 06 Mar 2008 10:57:15 -0800 Subject: errata for Contributed-by In-Reply-To: jonathan.gibbons@sun.com; Thu, 06 Mar 2008 10:18:36 PST; <47D0357C.7060309@sun.com> Message-ID: <20080306185716.03A862789B6@eggemoggin.niobe.net> > Date: Thu, 06 Mar 2008 10:18:36 -0800 > From: jonathan.gibbons at sun.com > http://openjdk.java.net/guide/producingChangeset.html#create lists this > example for a changeset message: > > 1234567: NPE thrown on FileInputStream("") > Summary: Rewrite precondition-checking code in io.c > Reviewed-by: mr > Contributed-by: Ben Bitdiddle > > In practice, it seems jcheck requires a real email address. At any > rate, it gave me an unspecific "invalid contributor attribution" when I > tried to follow the example. Yes, jcheck requires a real RFC-822 e-mail address. I suspect the address in the example got munged from to when Iris removed '@' signs in order to make spammers' lives (a little tiny bit) harder. I'll make a note to try to beef up the jcheck diagnostic in this case -- right now it's just a big regex. - Mark From iris at sun.com Thu Mar 6 15:12:08 2008 From: iris at sun.com (iris clark) Date: Thu, 6 Mar 2008 15:12:08 -0800 (PST) Subject: errata for Contributed-by In-Reply-To: <47D0357C.7060309@sun.com> (message from Jonathan Gibbons on Thu, 06 Mar 2008 10:18:36 -0800) Message-ID: <200803062312.m26NC8hY029063@ribbit.SFBay.Sun.COM> > Date: Thu, 06 Mar 2008 10:18:36 -0800 > From: Jonathan Gibbons > Subject: errata for Contributed-by > > http://openjdk.java.net/guide/producingChangeset.html#create lists this > example for a changeset message: > > 1234567: NPE thrown on FileInputStream("") > Summary: Rewrite precondition-checking code in io.c > Reviewed-by: mr > Contributed-by: Ben Bitdiddle > > In practice, it seems jcheck requires a real email address. At any rate, > it gave me > an unspecific "invalid contributor attribution" when I tried to follow > the example. Oops. When I was removing "@" from e-mail addresses, I was just a tiny bit too aggressive. :( I'll have to see what jcheck looks for. I'm hoping that it allows the something like this: Contributed-by: Ben Bitdiddle Rather than just Contributed-by: ben at bits.org iris From Bradford.Wetmore at Sun.COM Thu Mar 6 15:29:41 2008 From: Bradford.Wetmore at Sun.COM (Brad Wetmore) Date: Thu, 06 Mar 2008 15:29:41 -0800 Subject: Per-component repositories In-Reply-To: <200803052054.m25KsZRK028272@ribbit.SFBay.Sun.COM> References: <200803052054.m25KsZRK028272@ribbit.SFBay.Sun.COM> Message-ID: <47D07E65.6030002@sun.com> > For instance, as a developer in Core Libraries, it would seem that I only need > to retrieve the "jdk" portion of the repository since that's where the > implementation of those classes resides. However, I would need to be pretty > confident to not do a full build of the entire forest before I did my commit. I would like to offer the following guidance. If you're changing the layout of any part of the JDK, you really should do a full build on the whole repository, at least including images (generally as the last step before integrating). Yes, the file may have compiled correctly, but then something such as the images target broke, or the file wasn't included in the final rt.jar. There's a lot more than javac to be concerned with when you're moving target files around. Gatekeepers don't particularly enjoy last minute images target breakage. ;) > Yes, from the Guide, "Terminology and Naming Scheme": > > The OpenJDK repository forests are located at http://hg.openjdk.java.net/. There was talk that the output might be tweaked into logical chunks, and not alphabetical. I don't think it's in the immediate plans, but still would be nice. i.e. jdk7/2d jdk7/2d/corba jdk7/2d/hotspot jdk7/2d/jaxp jdk7/2d/jaxws jdk7/2d/jdk jdk7/2d/langtools jdk7/2d-gate jdk7/2d-gate/corba jdk7/2d-gate/hotspot jdk7/2d-gate/jaxp jdk7/2d-gate/jaxws jdk7/2d-gate/jdk jdk7/2d-gate/langtools > - MASTER ...deleted... > - tl > - jsn At least for JSN, that is correct. JSN is a "child" of TL because our code tends to be very interconnected, and having separate integration slots proved to be dangerous. Brad From iris at sun.com Thu Mar 6 16:48:29 2008 From: iris at sun.com (iris clark) Date: Thu, 6 Mar 2008 16:48:29 -0800 (PST) Subject: summary page for process workflow? In-Reply-To: <47CF1ACF.2010708@sun.com> (message from Jonathan Gibbons on Wed, 05 Mar 2008 14:12:31 -0800) Message-ID: <200803070048.m270mTWh029135@ribbit.SFBay.Sun.COM> Hi, Jon. > For my part, a quick reference guide is useful, more details than a > flow chart, but less detailed than multiple pages of info. I've been > developing one for myself and other compiler folk. Having it be > hyperlinked into more detailed pages would be good. I'll attach the > one I've been using for myself, as an example. Obviously, this one is > specific to the compiler team, but you get the idea. Thanks for the sample. I like it, though I'd argue about the content. For instance, you list approvals after review when in fact, some people might argue that some approvals need to be started before the code is finalized for review. Also, several bug database updates are missing. Perhaps I should enhanced the present set of steps on this page to contain a few key shell commands and references to appropriate tools: http://openjdk.java.net/guide/changePlanning.html Then provide a condensed version of those steps? iris From Jonathan.Gibbons at Sun.COM Thu Mar 6 17:10:02 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Thu, 06 Mar 2008 17:10:02 -0800 Subject: summary page for process workflow? In-Reply-To: <200803070048.m270mTWh029135@ribbit.SFBay.Sun.COM> References: <200803070048.m270mTWh029135@ribbit.SFBay.Sun.COM> Message-ID: <47D095EA.4000802@sun.com> Iris, What I sent was a work in progress of things that have tripped me up one way or another, and that I've found it useful to make notes about. Think of it as one person's real world checklist. I'm more than happy for you to use it as a basis for a more general purpose checklist. :-) The bold numbered headings on the changePlanning.html page also provide a good basis for a checklist. If you took those headings, added a quick hint to each one for the commands or websites involved, with links to the full page of details, then you'd have something pretty good, I think? -- Jon iris clark wrote: > Hi, Jon. > > >> For my part, a quick reference guide is useful, more details than a >> flow chart, but less detailed than multiple pages of info. I've been >> developing one for myself and other compiler folk. Having it be >> hyperlinked into more detailed pages would be good. I'll attach the >> one I've been using for myself, as an example. Obviously, this one is >> specific to the compiler team, but you get the idea. >> > > Thanks for the sample. I like it, though I'd argue about the content. > For instance, you list approvals after review when in fact, some > people might argue that some approvals need to be started before the > code is finalized for review. Also, several bug database updates are > missing. > > Perhaps I should enhanced the present set of steps on this page to > contain a few key shell commands and references to appropriate tools: > > http://openjdk.java.net/guide/changePlanning.html > > Then provide a condensed version of those steps? > > iris > -------------- next part -------------- An HTML attachment was scrubbed... URL: http://mail.openjdk.java.net/pipermail/guide-discuss/attachments/20080306/539d708c/attachment.html From iris at sun.com Thu Mar 6 20:00:08 2008 From: iris at sun.com (iris clark) Date: Thu, 6 Mar 2008 20:00:08 -0800 (PST) Subject: Per-component repositories In-Reply-To: <47D07E65.6030002@sun.com> (message from Brad Wetmore on Thu, 06 Mar 2008 15:29:41 -0800) Message-ID: <200803070400.m27408xI029311@ribbit.SFBay.Sun.COM> Hi. > > For instance, as a developer in Core Libraries, it would seem that I only need > > to retrieve the "jdk" portion of the repository since that's where the > > implementation of those classes resides. However, I would need to be pretty > > confident to not do a full build of the entire forest before I did my commit. > > I would like to offer the following guidance. > > If you're changing the layout of any part of the JDK, you really should > do a full build on the whole repository, at least including images > (generally as the last step before integrating). Yes, the file may have > compiled correctly, but then something such as the images target broke, > or the file wasn't included in the final rt.jar. There's a lot more > than javac to be concerned with when you're moving target files around. > Gatekeepers don't particularly enjoy last minute images target > breakage. ;) I think that thare are many types of changes for which I'd advise full builds prior to commit. Off the top of my head, here are a few more cases that I've run into: - A new class is added as part of the change. The unqualified class name is identical to that of another class in a different package. If any existing class in the JDK happens to do a star import of both packages and uses the unqualified class name, the compiler will report an ambiguity. Here's a short example: import java.awt.*; import java.util.*; class A extends List {} Believe it or not, this sort of thing happended during my very first integration! - If you work with incremental builds and are modifing any files which are built during bootstrap, it's possible that those files may compile just fine after bootstrap, but they won't compile during bootstrap. - Just because an API isn't public, doesn't mean that other parts of the JDK don't depend on its presence or precise semantics. At best, this is found during a full build. At worst the problem isn't found until an application/test is run. (Yes, that means they were probably using reflection.) There are multiple horror stories. I'd say that these cases are rare, but I'm sure any gatekeeper ("integrator" if you're using the old terminology) will appreciate if a full build was done at some point prior to commit. I stand by my statement that any developer working with only part of the forest needs to be extremely comfortable with the build structure and any potential side-effects their modifications may cause. iris From mr at sun.com Thu Mar 6 21:13:32 2008 From: mr at sun.com (Mark Reinhold) Date: Thu, 06 Mar 2008 21:13:32 -0800 Subject: errata for Contributed-by In-Reply-To: iris@sun.com; Thu, 06 Mar 2008 15:12:08 PST; <200803062312.m26NC8hY029063@ribbit.SFBay.Sun.COM> Message-ID: <20080307051332.F157E7C10@callebaut.niobe.net> > Date: Thu, 06 Mar 2008 15:12:08 -0800 (PST) > From: iris clark >> Date: Thu, 06 Mar 2008 10:18:36 -0800 >> From: jonathan.gibbons at sun.com >> >> http://openjdk.java.net/guide/producingChangeset.html#create lists this >> example for a changeset message: >> >> 1234567: NPE thrown on FileInputStream("") >> Summary: Rewrite precondition-checking code in io.c >> Reviewed-by: mr >> Contributed-by: Ben Bitdiddle >> >> In practice, it seems jcheck requires a real email address. At any >> rate, it gave me an unspecific "invalid contributor attribution" when >> I tried to follow the example. > > Oops. When I was removing "@" from e-mail addresses, I was just a > tiny bit too aggressive. > > :( > > I'll have to see what jcheck looks for. I'm hoping that it allows the > something like this: > > Contributed-by: Ben Bitdiddle > > Rather than just > > Contributed-by: ben at bits.org Yes, it allows the former long form, and in fact that's preferable. The long form will make the CONTRIBUTORS file (or whatever we wind up calling it) easier to read. Hmm, perhaps jcheck should require the long form? Some people don't ever use their full names, and are just known by bare e-mail addresses, so I suppose that won't work. - Mark From iris at sun.com Thu Mar 6 21:12:46 2008 From: iris at sun.com (iris clark) Date: Thu, 6 Mar 2008 21:12:46 -0800 (PST) Subject: summary page for process workflow? In-Reply-To: <7165331D-1B42-4F02-B9D8-5F3898CCD5F9@Sun.COM> (message from Jonathan Gibbons on Wed, 05 Mar 2008 09:08:54 -0800) Message-ID: <200803070512.m275CkVc029344@ribbit.SFBay.Sun.COM> Hi. > > I'd also like to see a way to get it all in one html page so I could > > potentially print it. Call me old-fashioned. ;^) I'll use recycled > > paper. The planned conversion to DocBook [1] should help out with this and other publishing-related issues: http://openjdk.java.net/guide/intro.html The guide is presently written in raw html. It will be converted into docbook format soon. Since we're moving to another format, I didn't spent too much time obsessing over various annoying cosmetic issues. iris [1] http://www.docbook.org/ From Jonathan.Gibbons at Sun.COM Fri Mar 7 14:24:55 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Fri, 07 Mar 2008 14:24:55 -0800 Subject: guide: errata and suggestion Message-ID: <47D1C0B7.3030606@sun.com> Errata: On the page http://openjdk.java.net/guide/changePlanning.html#feature the bug states listed are pre-Bugster. They should be updated to the current terminology -- eg. "8-Fix Available" Suggestion: This one is a hot topic today :-( I know "Adding an API" is TBD, but when you do get around to writing it, please can you make sure to note that if you're adding a package you need to update the contents of the API bundle in jdk/make/docs/*.gmk. -- Jon From Bradford.Wetmore at Sun.COM Fri Mar 7 16:37:15 2008 From: Bradford.Wetmore at Sun.COM (Brad Wetmore) Date: Fri, 07 Mar 2008 16:37:15 -0800 Subject: Per-component repositories In-Reply-To: <200803070400.m27408xI029311@ribbit.SFBay.Sun.COM> References: <200803070400.m27408xI029311@ribbit.SFBay.Sun.COM> Message-ID: <47D1DFBB.8070600@sun.com> > I think that thare are many types of changes for which I'd advise full > builds prior to commit. Off the top of my head, here are a few more > cases that I've run into: There are *PLENTY* of cases. I debating brainstorming a more complete list, but thought my email was long enough already. :) > - Just because an API isn't public, doesn't mean that other parts of > the JDK don't depend on its presence or precise semantics. Deploy used to break quite a bit due to sun.* changes. That's why gatekeepers really need to build most of the gates, at least as far as images. > I'd say that these cases are rare, but I'm sure any gatekeeper > ("integrator" if you're using the old terminology) will appreciate if > a full build was done at some point prior to commit. Agreed, I'm happy to give the "noose" [1] for extra-careless acts. Extra points if you identify the office who last received it. ;) Brad [1] http://blogs.sun.com/wetmore/resource/images/PowerNoose.JPG From iris at sun.com Mon Mar 10 14:39:33 2008 From: iris at sun.com (iris clark) Date: Mon, 10 Mar 2008 13:39:33 -0800 (PST) Subject: guide: errata and suggestion In-Reply-To: <47D1C0B7.3030606@sun.com> (message from Jonathan Gibbons on Fri, 07 Mar 2008 14:24:55 -0800) Message-ID: <200803102139.m2ALdXXN000937@ribbit.SFBay.Sun.COM> Hi, Jon. > Errata: > On the page http://openjdk.java.net/guide/changePlanning.html#feature > the bug states listed are pre-Bugster. They should be updated to the > current terminology -- eg. "8-Fix Available" I can see how this can be confusing. I personally don't think of the state numbers as part of the state name, I just think "Fix Available", but you are correct, in this context we should always use the complete name of the states. I've updated this in my working repository. > Suggestion: > This one is a hot topic today :-( I know "Adding an API" is TBD, but > when you do get around to writing it, > please can you make sure to note that if you're adding a package you > need to update the contents of the > API bundle in jdk/make/docs/*.gmk. I've added a note to that effect. This reminds me that I really need to find a way to incorporate my "todo" list into the main-line document. It isn't critical for people to see all of the small corrections I need to remind myself to do (they should just be made), but I think it is necessary to track issues for sections which will be written in the future. Thanks, iris From Jonathan.Gibbons at Sun.COM Fri Mar 14 17:00:09 2008 From: Jonathan.Gibbons at Sun.COM (Jonathan Gibbons) Date: Fri, 14 Mar 2008 17:00:09 -0700 Subject: http://openjdk.java.net/guide/repositories.html#term Message-ID: <47DB1189.7080301@sun.com> > > > The repositories use following naming scheme: > > |/{-gate}?/| > > where > > /release/ :: the name of the release such as "jdk7" > /project/ :: the name of an OpenJDK project > such as "swing", "tl", or "modules" > /component/ :: the name of a repository containing a logical subset > of the code base such as "langtools" > "swing" and "tl" are not OpenJDK projects are they? They're certainly not listed under "Projects" in the list on the left of the page. "Integration-family or project", maybe? -- Jon -------------- next part -------------- An HTML attachment was scrubbed... URL: http://mail.openjdk.java.net/pipermail/guide-discuss/attachments/20080314/e9713784/attachment.html From iris at sun.com Mon Mar 17 13:48:11 2008 From: iris at sun.com (iris clark) Date: Mon, 17 Mar 2008 12:48:11 -0800 (PST) Subject: http://openjdk.java.net/guide/repositories.html#term In-Reply-To: <47DB1189.7080301@sun.com> (message from Jonathan Gibbons on Fri, 14 Mar 2008 17:00:09 -0700) Message-ID: <200803172048.m2HKmB1W004494@ribbit.SFBay.Sun.COM> Hi, Jon. > "swing" and "tl" are not OpenJDK projects are they? They're certainly > not listed under "Projects" in the list on the left of the page. > "Integration-family or project", maybe? Yes, this is a problem. The provided naming scheme reflects the discussion we had when the repositories were originally being discussed/designed. The actual names "swing", "tl", etc. reflect the historical names of the integration units as somewhat defined by our org structure. I like your suggestion. Let me see how changing to "integration family" plays out in the rest of the document, before I commit to it. iris From Bradford.Wetmore at Sun.COM Wed Mar 19 12:45:27 2008 From: Bradford.Wetmore at Sun.COM (Brad Wetmore) Date: Wed, 19 Mar 2008 12:45:27 -0700 Subject: Picture/Thousand Words Message-ID: <47E16D57.6040702@sun.com> Iris, There was a somewhat lengthy discussion recently on build-dev about the layout of the various repositories, and how it's been difficult to keep them straight. On: http://openjdk.java.net/guide/repositories.html You might want to put a quick example in here somewhere that the toplevel (MASTER) of the openjdk7 project is actually: http://hg.openjdk.java.net/jdk7/jdk7 It wasn't really clear that the second jdk7 is the name for MASTER, that which RE builds. Also a comment was made which would be a great addition to the guide: David Herron wrote: ---begin--- I think there is a problem here of trying to describe with words a thing that's better described with a picture. ...deleted... I see Kelly's blog [1] has the right picture. I think that picture belongs in the developers guide... [1] http://blogs.sun.com/kto/entry/openjdk_mercurial_wheel ---end--- I've also done a picture for explaining the gatekeeping process in my own blog [2]. [2] http://blogs.sun.com/wetmore/entry/you_re_a_gatekeeper_uh I think we could improve upon that further by addition all of the subrepositories. I'll drawn a picture and left the original on your desk. If you think it's worth it, we can get someone with better art skills than I to do the final drawing. Yes, I know my handwriting sucks... ;) (I tried to post to the alias, but the list only allows attachments up to 40kb). Brad