|
Replies:
12
-
Last Post:
Mar 13, 2008 3:21 PM
by: michelle
|
Threads:
[
Previous
|
Next
]
|
|
Posts:
62
From:
Registered:
5/30/06
|
|
|
|
New Developer Checklist
Posted:
Mar 4, 2008 12:21 PM
To: Communities » documentation » discuss
|
|
I've been poking around for a while and although there's lots of good documentation for many things I can't find a step by step list of things you need to do to contribute code.
I'm not talking about some behemoth like the OpenSolaris Developers Reference (which is also missing things like how to generate a webrev), but something more like:
0. Create a workspace and become familiar with building (pointer to docs (maybe also http://www.opensolaris.org/os/community/on/install_quickstart/)) 1. Find or file a bug (http://bugs.opensolaris.org or http://defect.opensolaris.org) 2. Request a sponsor (pointer to sponsor documentation) 2.1 If it's large amounts of code or adding a binary/library (give list of other things that might require ARC) then file an ARC case (link to ARC docs) 3. Write code (link to dev guides) 3.1 Check your code meets style (pointer to style section of docs) 3.2 Other pre-build checks you should do (e.g. IPv6) may be a pre-build checklist or list of pointers to sections of the dev guide 4. Build and test code 5. Generate and upload a webrev (pointer to webrev documentation (which seems to only be here http://blogs.sun.com/tdh/entry/getting_a_webrev_generated_for)) 6. Request code review from your sponsor 7. Fix any bugs pointed out by the sponsor 8. goto 4 9. Done?
Does such a thing exist and my search foo is failing? Such a thing would be great from a "New to developing OpenSolaris? Here's the checklist" point of view as it's a single place to go, has pointers to everything you need to know and is short so it's not overwhelming (and is also easier to consume for a programmer who only has a small number of hours a week to devote to OpenSolaris).
Paul
|
|
|
Posts:
1,273
From:
US
Registered:
10/6/05
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 4, 2008 3:11 PM
in response to: psa
|
|
Hi Paul,
Thanks for writing up this list, I don't think it exists somewhere else. I'd suggest that you request technical review of this content on the request-sponsor discussion list, just to ensure there are no inaccuracies or omissions. Then, I think it should be added to the information on this page, or added as a child page to this one: http://opensolaris.org/os/communities/participation/#code
We should of course link to it from the docs community pages wherever it is most appropriate. I'm happy to help conduct or request these reviews and help to get changes made to the participation page above to make things more clear. Alysson Troffer is our contact on the editorial board for the web site, so I copy her here. I appreciate your time to write this up and send it out.
Regards, Michelle Olson OpenSolaris Documentation Community Leader
Paul Armstrong wrote: > I've been poking around for a while and although there's lots of good documentation for many things I can't find a step by step list of things you need to do to contribute code. > > I'm not talking about some behemoth like the OpenSolaris Developers Reference (which is also missing things like how to generate a webrev), but something more like: > > 0. Create a workspace and become familiar with building (pointer to docs (maybe also http://www.opensolaris.org/os/community/on/install_quickstart/)) > 1. Find or file a bug (http://bugs.opensolaris.org or http://defect.opensolaris.org) > 2. Request a sponsor (pointer to sponsor documentation) > 2.1 If it's large amounts of code or adding a binary/library (give list of other things that might require ARC) then file an ARC case (link to ARC docs) > 3. Write code (link to dev guides) > 3.1 Check your code meets style (pointer to style section of docs) > 3.2 Other pre-build checks you should do (e.g. IPv6) may be a pre-build checklist or list of pointers to sections of the dev guide > 4. Build and test code > 5. Generate and upload a webrev (pointer to webrev documentation (which seems to only be here http://blogs.sun.com/tdh/entry/getting_a_webrev_generated_for)) > 6. Request code review from your sponsor > 7. Fix any bugs pointed out by the sponsor > 8. goto 4 > 9. Done? > > Does such a thing exist and my search foo is failing? > Such a thing would be great from a "New to developing OpenSolaris? Here's the checklist" point of view as it's a single place to go, has pointers to everything you need to know and is short so it's not overwhelming (and is also easier to consume for a programmer who only has a small number of hours a week to devote to OpenSolaris). > > Paul > > > This message posted from opensolaris.org > _______________________________________________ > docs-discuss mailing list > docs-discuss at opensolaris dot org >
_______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
651
From:
CA
Registered:
6/14/05
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 4, 2008 4:31 PM
in response to: michelle
|
|
+1
Thanks for helping with this, Michelle. I think Paul has a great idea. I seem to remember reading that our code contribution process can be pretty opaque.
Thanks in advance to Allyson for her help with the web site.
Do we want this list to include the PSARC process, or can that be considered being part of the sponsor item? If so, might it help anyway so new code contributors know what will happen?
Michelle Olson wrote: > Hi Paul, > > Thanks for writing up this list, I don't think it exists somewhere else. > I'd suggest that you request technical review of this content on the > request-sponsor discussion list, just to ensure there are no > inaccuracies or omissions. Then, I think it should be added to the > information on this page, or added as a child page to this one: > http://opensolaris.org/os/communities/participation/#code > > We should of course link to it from the docs community pages wherever it > is most appropriate. I'm happy to help conduct or request these reviews > and help to get changes made to the participation page above to make > things more clear. Alysson Troffer is our contact on the editorial board > for the web site, so I copy her here. I appreciate your time to write > this up and send it out. > > Regards, > Michelle Olson > OpenSolaris Documentation Community Leader > > > Paul Armstrong wrote: >> I've been poking around for a while and although there's lots of good documentation for many things I can't find a step by step list of things you need to do to contribute code. >> >> I'm not talking about some behemoth like the OpenSolaris Developers Reference (which is also missing things like how to generate a webrev), but something more like: >> >> 0. Create a workspace and become familiar with building (pointer to docs (maybe also http://www.opensolaris.org/os/community/on/install_quickstart/)) >> 1. Find or file a bug (http://bugs.opensolaris.org or http://defect.opensolaris.org) >> 2. Request a sponsor (pointer to sponsor documentation) >> 2.1 If it's large amounts of code or adding a binary/library (give list of other things that might require ARC) then file an ARC case (link to ARC docs) >> 3. Write code (link to dev guides) >> 3.1 Check your code meets style (pointer to style section of docs) >> 3.2 Other pre-build checks you should do (e.g. IPv6) may be a pre-build checklist or list of pointers to sections of the dev guide >> 4. Build and test code >> 5. Generate and upload a webrev (pointer to webrev documentation (which seems to only be here http://blogs.sun.com/tdh/entry/getting_a_webrev_generated_for)) >> 6. Request code review from your sponsor >> 7. Fix any bugs pointed out by the sponsor >> 8. goto 4 >> 9. Done? >> >> Does such a thing exist and my search foo is failing? >> Such a thing would be great from a "New to developing OpenSolaris? Here's the checklist" point of view as it's a single place to go, has pointers to everything you need to know and is short so it's not overwhelming (and is also easier to consume for a programmer who only has a small number of hours a week to devote to OpenSolaris). >> >> Paul
Rainer -- Mind the gap. _______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
651
From:
CA
Registered:
6/14/05
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 4, 2008 4:32 PM
in response to: michelle
|
|
+1
Thanks for helping with this, Michelle. I think Paul has a great idea. I seem to remember reading that our code contribution process can be pretty opaque.
Thanks in advance to Alysson for her help with the web site.
Do we want this list to include the PSARC process, or can that be considered being part of the sponsor item? If so, might it help anyway so new code contributors know what will happen?
Michelle Olson wrote: > Hi Paul, > > Thanks for writing up this list, I don't think it exists somewhere else. > I'd suggest that you request technical review of this content on the > request-sponsor discussion list, just to ensure there are no > inaccuracies or omissions. Then, I think it should be added to the > information on this page, or added as a child page to this one: > http://opensolaris.org/os/communities/participation/#code > > We should of course link to it from the docs community pages wherever it > is most appropriate. I'm happy to help conduct or request these reviews > and help to get changes made to the participation page above to make > things more clear. Alysson Troffer is our contact on the editorial board > for the web site, so I copy her here. I appreciate your time to write > this up and send it out. > > Regards, > Michelle Olson > OpenSolaris Documentation Community Leader > > > Paul Armstrong wrote: >> I've been poking around for a while and although there's lots of good documentation for many things I can't find a step by step list of things you need to do to contribute code. >> >> I'm not talking about some behemoth like the OpenSolaris Developers Reference (which is also missing things like how to generate a webrev), but something more like: >> >> 0. Create a workspace and become familiar with building (pointer to docs (maybe also http://www.opensolaris.org/os/community/on/install_quickstart/)) >> 1. Find or file a bug (http://bugs.opensolaris.org or http://defect.opensolaris.org) >> 2. Request a sponsor (pointer to sponsor documentation) >> 2.1 If it's large amounts of code or adding a binary/library (give list of other things that might require ARC) then file an ARC case (link to ARC docs) >> 3. Write code (link to dev guides) >> 3.1 Check your code meets style (pointer to style section of docs) >> 3.2 Other pre-build checks you should do (e.g. IPv6) may be a pre-build checklist or list of pointers to sections of the dev guide >> 4. Build and test code >> 5. Generate and upload a webrev (pointer to webrev documentation (which seems to only be here http://blogs.sun.com/tdh/entry/getting_a_webrev_generated_for)) >> 6. Request code review from your sponsor >> 7. Fix any bugs pointed out by the sponsor >> 8. goto 4 >> 9. Done? >> >> Does such a thing exist and my search foo is failing? >> Such a thing would be great from a "New to developing OpenSolaris? Here's the checklist" point of view as it's a single place to go, has pointers to everything you need to know and is short so it's not overwhelming (and is also easier to consume for a programmer who only has a small number of hours a week to devote to OpenSolaris). >> >> Paul
Rainer -- Mind the gap. _______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
1,273
From:
US
Registered:
10/6/05
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 4, 2008 5:14 PM
in response to: rheilke
|
|
Hi Rainer,
I believe there is more than one ARC, so maybe we just link to another web page that describes the processes for these different architecture review committees, or dig around the ARC community site? But, ARC processes, from what I understand, are only required in some cases, so they should only be a 'branch' of this procedure.
I put the first draft from Paul on genunix, so we can work on it together and at least fill in the links he suggests. http://www.genunix.org/wiki/index.php/Developer_HOWTO
-Michelle
Rainer Heilke wrote: > +1 > > Thanks for helping with this, Michelle. I think Paul has a great idea. > I seem to remember reading that our code contribution process can be > pretty opaque. > > Thanks in advance to Alysson for her help with the web site. > > Do we want this list to include the PSARC process, or can that be > considered being part of the sponsor item? If so, might it help anyway > so new code contributors know what will happen? > > Michelle Olson wrote: >> Hi Paul, >> >> Thanks for writing up this list, I don't think it exists somewhere >> else. I'd suggest that you request technical review of this content >> on the request-sponsor discussion list, just to ensure there are no >> inaccuracies or omissions. Then, I think it should be added to the >> information on this page, or added as a child page to this one: >> http://opensolaris.org/os/communities/participation/#code >> >> We should of course link to it from the docs community pages wherever >> it is most appropriate. I'm happy to help conduct or request these >> reviews and help to get changes made to the participation page above >> to make things more clear. Alysson Troffer is our contact on the >> editorial board for the web site, so I copy her here. I appreciate >> your time to write this up and send it out. >> >> Regards, >> Michelle Olson >> OpenSolaris Documentation Community Leader >> >> >> Paul Armstrong wrote: >>> I've been poking around for a while and although there's lots of >>> good documentation for many things I can't find a step by step list >>> of things you need to do to contribute code. >>> >>> I'm not talking about some behemoth like the OpenSolaris Developers >>> Reference (which is also missing things like how to generate a >>> webrev), but something more like: >>> >>> 0. Create a workspace and become familiar with building (pointer to >>> docs (maybe also >>> http://www.opensolaris.org/os/community/on/install_quickstart/)) >>> 1. Find or file a bug (http://bugs.opensolaris.org or >>> http://defect.opensolaris.org) >>> 2. Request a sponsor (pointer to sponsor documentation) >>> 2.1 If it's large amounts of code or adding a binary/library (give >>> list of other things that might require ARC) then file an ARC case >>> (link to ARC docs) >>> 3. Write code (link to dev guides) >>> 3.1 Check your code meets style (pointer to style section of docs) >>> 3.2 Other pre-build checks you should do (e.g. IPv6) may be a >>> pre-build checklist or list of pointers to sections of the dev guide >>> 4. Build and test code >>> 5. Generate and upload a webrev (pointer to webrev documentation >>> (which seems to only be here >>> http://blogs.sun.com/tdh/entry/getting_a_webrev_generated_for)) >>> 6. Request code review from your sponsor >>> 7. Fix any bugs pointed out by the sponsor >>> 8. goto 4 >>> 9. Done? >>> >>> Does such a thing exist and my search foo is failing? >>> Such a thing would be great from a "New to developing OpenSolaris? >>> Here's the checklist" point of view as it's a single place to go, >>> has pointers to everything you need to know and is short so it's not >>> overwhelming (and is also easier to consume for a programmer who >>> only has a small number of hours a week to devote to OpenSolaris). >>> >>> Paul > > Rainer
_______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
62
From:
Registered:
5/30/06
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 8, 2008 11:00 PM
in response to: michelle
To: Communities » documentation » discuss
|
|
> I believe there is more than one ARC, so maybe we > just link to another > web page that describes the processes for these > different architecture > review committees, or dig around the ARC community > site?
Linking to the appropriate doc would be useful. Maybe my search foo sucks, but I can't for example find the difference between PSARC and normal ARC after 30 minutes of searching the ARC site. The glossary would be a good place for such definitions IMHO.
I did however find a typo on http://opensolaris.org/os/community/arc/ This link: http://opensolaris.org/os/community/arc/faq/arc-review-overview should say: http://opensolaris.org/os/community/arc/arc-faq/arc-review-overview
Is documentation the right place to bring up such bugs (both the typo and the hard to find information on the ARC site) or is that the responsibility of the ARC community?
> But, ARC > processes, from what I understand, are only required > in some cases, so > they should only be a 'branch' of this procedure.
The docs for ARC are kind of messy and repetitive. They keep coming back to the same diagram and occasionally providing a bit more insight below it (or that's my impression). They also have things like "mail internal Sun alias" in them and a reference to not yet having an SCM.
> I put the first draft from Paul on genunix, so we can > work on it > together and at least fill in the links he suggests. > http://www.genunix.org/wiki/index.php/Developer_HOWTO
Cool. Thank you. I've made a couple of updates from tonight's searches (although I suspect there are better links than the ones I've put in).
Paul
|
|
|
|
Posts:
1,273
From:
US
Registered:
10/6/05
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 10, 2008 12:40 PM
in response to: psa
|
|
Paul Armstrong wrote: >> I believe there is more than one ARC, so maybe we >> just link to another >> web page that describes the processes for these >> different architecture >> review committees, or dig around the ARC community >> site? >> > > Linking to the appropriate doc would be useful. > Maybe my search foo sucks, but I can't for example find the difference between PSARC and normal ARC after 30 minutes of searching the ARC site. The glossary would be a good place for such definitions IMHO. > > I did however find a typo on http://opensolaris.org/os/community/arc/ > This link: > http://opensolaris.org/os/community/arc/faq/arc-review-overview > should say: > http://opensolaris.org/os/community/arc/arc-faq/arc-review-overview > > Is documentation the right place to bring up such bugs (both the typo and the hard to find information on the ARC site) or is that the responsibility of the ARC community? > > These issues are the responsibility of the ARC community, I copy their list here. But, we can certainly develop terms and definitions to add to the glossary suing docs-discuss and the wiki draft. >> But, ARC >> processes, from what I understand, are only required >> in some cases, so >> they should only be a 'branch' of this procedure. >> > > The docs for ARC are kind of messy and repetitive. They keep coming back to the same diagram and occasionally providing a bit more insight below it (or that's my impression). They also have things like "mail internal Sun alias" in them and a reference to not yet having an SCM. > If you can provide specific pointers to problem areas, I'm sure the ARC folks will clean them up. > >> I put the first draft from Paul on genunix, so we can >> work on it >> together and at least fill in the links he suggests. >> http://www.genunix.org/wiki/index.php/Developer_HOWTO >> > > Cool. Thank you. I've made a couple of updates from tonight's searches (although I suspect there are better links than the ones I've put in). > > Paul > You bet, I'll try to do some more with on those definitions this week if we hear back form the ARC on difference between PSARC and ARC, etc.
Thanks, Michelle > > > This message posted from opensolaris.org > _______________________________________________ > docs-discuss mailing list > docs-discuss at opensolaris dot org >
_______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
1,495
From:
Registered:
5/18/05
|
|
|
|
Re: [arc-discuss] New Developer Checklist
Posted:
Mar 10, 2008 12:52 PM
in response to: michelle
|
|
Michelle Olson wrote: >> Maybe my search foo sucks, but I can't for example find the difference between PSARC and normal ARC after 30 minutes of searching the ARC site. The glossary would be a good place for such definitions IMHO.
PSARC is the name of one of Sun's internal ARCs - it focuses on Platform Software. Others include LSARC - layered software and middleware and web services, and FWARC (for firmware related stuff). Together they are "the ARC"; individually they are simply the way we distribute and scale the review process; the number and scope of XXARCs change regularly over time as needs change.
There is a nascent ARC CG project that will be addressing the question of "what is the relationship of the ARC community to the rest of the OpenSolaris effort?"; keep an eye out for it soon after the election is over - and please, feel free to join us.
>> I did however find a typo on http://opensolaris.org/os/community/arc/ >> This link: >> http://opensolaris.org/os/community/arc/faq/arc-review-overview >> should say: >> http://opensolaris.org/os/community/arc/arc-faq/arc-review-overview
Thanks, fixed.
>> The docs for ARC are kind of messy and repetitive. They keep coming back to the same diagram and occasionally providing a bit more insight below it (or that's my impression). They also have things like "mail internal Sun alias" in them and a reference to not yet having an SCM. >>
This is one of the things this new project is intended to address.
-John _______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
59
From:
US
Registered:
4/17/07
|
|
|
|
Re: [arc-discuss] New Developer Checklist
Posted:
Mar 10, 2008 1:25 PM
in response to: plocher
To: Communities » documentation » discuss
|
|
There is also CLARC, for the Sun Cluster development group. For the Open HA Clusters project, the CLARC process has been extended to the open-source community; see http://opensolaris.org/os/community/ha-clusters/ohac/contribute/CLARC/.
Lisa Shepherd
|
|
|
|
Posts:
62
From:
Registered:
5/30/06
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 11, 2008 1:37 AM
in response to: michelle
To: Communities » documentation » discuss
Cc: Communities » testing » discuss
|
|
> >> I put the first draft from Paul on genunix, so we can > >> work on it together and at least fill in the links he suggests. > >> > http://www.genunix.org/wiki/index.php/Developer_HOWTO > > > > Cool. Thank you. I've made a couple of updates from tonight's searches > > (although I suspect there are better links than the ones I've put in). > > > You bet, I'll try to do some more with on those definitions this week if > we hear back form the ARC on difference between PSARC > and ARC, etc.
I've updated it with the comments from John and Lisa (temporary holding area, should be added to some glossary really) as well as a few other links I came across.
Two other questions that're relevant to this doc and came up as I was writing a man page for a new command tonight: * Where do docs link in? * What should I do with small unit tests like the one I wrote for my new binary?
The docs consolidation is separate from OS/Net so it doesn't look like I can check in my man page with the c file and Makefile. The testing consolidation looks like it has similar issues (actually, it looks like there's no support for minor, localized unit tests at all but I could just be overlooking it).
I'm kind of in limbo as far as requesting a sponsor until my contributor number arrives, but I'm happy to work on documenting the process before then.
Paul
|
|
|
|
Posts:
1,273
From:
US
Registered:
10/6/05
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 13, 2008 3:21 PM
in response to: psa
|
|
Paul Armstrong wrote: >>>> I put the first draft from Paul on genunix, so we can >>>> work on it together and at least fill in the links he suggests. >>>> >>>> >> http://www.genunix.org/wiki/index.php/Developer_HOWTO >> >>> Cool. Thank you. I've made a couple of updates from tonight's searches >>> (although I suspect there are better links than the ones I've put in). >>> >>> >> You bet, I'll try to do some more with on those definitions this week if >> we hear back form the ARC on difference between PSARC >> and ARC, etc. >> > > I've updated it with the comments from John and Lisa (temporary holding area, should be added to some glossary really) as well as a few other links I came across. > > Two other questions that're relevant to this doc and came up as I was writing a man page for a new command tonight: > * Where do docs link in? > * What should I do with small unit tests like the one I wrote for my new binary? > > The docs consolidation is separate from OS/Net so it doesn't look like I can check in my man page with the c file and Makefile. The testing consolidation looks like it has similar issues (actually, it looks like there's no support for minor, localized unit tests at all but I could just be overlooking it). > > I'm kind of in limbo as far as requesting a sponsor until my contributor number arrives, but I'm happy to work on documenting the process before then. > > Paul > > > This message posted from opensolaris.org > _______________________________________________ > docs-discuss mailing list > docs-discuss at opensolaris dot org > Hi Paul,
Thanks for continuing to work on this new procedure and a new man page--you rock. Just as FYI, we have some man page templates here, so you'll know what sections to include (or not). http://opensolaris.org/os/community/documentation/doc_collab/manpageguide/
Can you give me more specific information about your first question above? You ask 'where do docs link in', but I need more information to understand what you're trying to do, what kind of docs, etc. I copy Jim Walker here for your unit test question, he is a leader of the Testing Community and can help us with your minor/localized/unit test questions.
You are right, the man page consolidation is separate from ON, (you say docs consolidation above, but that does not include man pages, so I assume that you mean to say man page consolidation. Assuming my assumptions are correct :) then, a man page associated with new ON code would go into the man page consolidation. Man pages associated with code outside of ON have their own package in some cases, or might be put back into the code consolidation with the c and makefile.
For example, Sun Cluster data services man pages in the OHAC consolidation, are co-located with the agent code because it makes sense to do so with a set of modular agents where you have a 1:1 mapping between a man page and an agent. For ON, there is no such 1:1 mapping and the scale is 1000X greater, so we centralize the man pages and manage/maintain them all together.
Hope this helps, thanks again for your time to work on this and for helping us to learn how to teach.
Regards, Michelle _______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
651
From:
CA
Registered:
6/14/05
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 4, 2008 4:34 PM
in response to: michelle
|
|
Sorry, I saw too late that I miss-typed Alysson's name in the first send... :-(
Rainer -- Mind the gap. _______________________________________________ docs-discuss mailing list docs-discuss at opensolaris dot org
|
|
|
|
Posts:
62
From:
Registered:
5/30/06
|
|
|
|
Re: New Developer Checklist
Posted:
Mar 8, 2008 10:02 PM
in response to: michelle
To: Communities » documentation » discuss
|
|
> I'd suggest that you request technical review of this > content on the > request-sponsor discussion list, just to ensure there > are no > inaccuracies or omissions.
OK, I'll do that as soon as I get my contributor number...
> Then, I think it should be added to the > information on this page, or added as a child page to > this one: > http://opensolaris.org/os/communities/participation/#code
My first thought is that it could just replace the contributing code section (or a large part of it at least).
Paul
|
|
|
|
|