Re: [openstack-dev] [all] creating a unified developer reference manual
Excerpts from Ben Nemec's message of 2015-02-27 09:25:37 -0800: > On 02/27/2015 03:54 AM, Thierry Carrez wrote: > > Doug Hellmann wrote: > >> Maybe some of the folks in the meeting who felt more strongly that it > >> should be a separate document can respond with their thoughts? > > > > I don't feel very strongly and could survive this landing in > > openstack-specs. My objection was the following: > > > > - Specs are for designing the solution and implementation plan to a > > specific problem. They are mainly used by developers and reviewers > > during implementation as a clear reference rationale for change and > > approved plan. Once they are fully implemented, they are kept for > > history purpose, not for constant reference. > > > > - Guidelines/developer doc are for all developers (old and new) to > > converge on best practices on topics that are not directly implemented > > as hacking rules. They are constantly used by everyone (not just > > developers/reviewers of a given feature) and never become "history". > > > > Putting guidelines doc in the middle of specs makes it a bit less > > discoverable imho, especially by our new developers. It's harder to > > determine which are still current and you should read. An "OpenStack > > developer doc" sounds like a much better entry point. > > > > That said, the devil is in the details, and some efforts start as specs > > (for existing code to catch up with the recommendation) and become > > guidelines (for future code being written). That is the case of the log > > levels spec: it is both a spec and a guideline. Personally I wouldn't > > object if that was posted in both areas, or if the relevant pieces were > > copied, once the current code has caught up, from the spec to a dev > > guideline. > > > > In the eventlet case, it's only a set of best practices / guidelines: > > there is no specific problem to solve, no catch-up plan for existing > > code to implement. Only a collection of recommendations if you get to > > write future eventlet-based code. Those won't start or end. Which is why > > I think it should go straight to a developer doc. > > > > Well, this whole spec arose because we found out there was existing code > that was doing bad things with eventlet monkey patching that needed to > be fixed. The specific problem is actually being worked concurrently > with the spec because everyone involved has agreed on a solution, which > became one of the guidelines in the spec. I'd be surprised if there > aren't other projects that need similar changes to be in line with the > new recommendations though. I'd hope that future projects will follow > the guidelines, but they were actually written for the purpose of > eliminating as many potential eventlet gotchas in our _current_ code as > possible. Coming up with a specific list of changes needed is tough > until we have agreement on the best practices though, which is why the > first work item is a somewhat vague "audit and fix all the things" point. > > Personally, I would expect most best practice/guideline type specs to be > similar. Nobody's going to take the time to write up a spec about > something everyone's already doing - they're going to do it because one > or a few projects have found something that works well and they think > everyone should be doing it. So I think your point about most of these > things moving from spec to guideline throughout their lifetime is spot > on, I'm just wondering if it's worth complicating the workflow for that > process. Herding the cats for something big like the log guidelines is > hard enough without requiring two separate documents for the immediate > work and the long-term information. > > That said, I agree with the points about publishing this stuff under a > developer reference doc rather than specs, and if that can't be done in > a single repo maybe we do have to split. I'd still prefer to keep it > all in one repo though - moving a doc between directories is a lot > simpler than moving it between repos (and also doesn't lose any previous > discussion in Gerrit). > There are numerous wiki pages that have a wealth of knowledge, but very poor history attached. Such as: * https://wiki.openstack.org/wiki/Python3 * https://wiki.openstack.org/wiki/GitCommitMessages * https://wiki.openstack.org/wiki/Gerrit_Workflow * https://wiki.openstack.org/wiki/Getting_The_Code * https://wiki.openstack.org/wiki/Testr Just having these in git would be useful, and having the full change history with the same care given to commit messages and with reviewers would I think improve the content and usability of these. Since these are not even close to "specs", but make excellent static documents, I think having them in a cross-project developer documentation repository makes a lot of sense. That said, I do think that we would need to have a much lower bar for reviews (maybe just 1 * +2, but let it sit at least 3 days or something to allow for exposur
Re: [openstack-dev] [all] creating a unified developer reference manual
On 02/27/2015 03:54 AM, Thierry Carrez wrote: > Doug Hellmann wrote: >> Maybe some of the folks in the meeting who felt more strongly that it >> should be a separate document can respond with their thoughts? > > I don't feel very strongly and could survive this landing in > openstack-specs. My objection was the following: > > - Specs are for designing the solution and implementation plan to a > specific problem. They are mainly used by developers and reviewers > during implementation as a clear reference rationale for change and > approved plan. Once they are fully implemented, they are kept for > history purpose, not for constant reference. > > - Guidelines/developer doc are for all developers (old and new) to > converge on best practices on topics that are not directly implemented > as hacking rules. They are constantly used by everyone (not just > developers/reviewers of a given feature) and never become "history". > > Putting guidelines doc in the middle of specs makes it a bit less > discoverable imho, especially by our new developers. It's harder to > determine which are still current and you should read. An "OpenStack > developer doc" sounds like a much better entry point. > > That said, the devil is in the details, and some efforts start as specs > (for existing code to catch up with the recommendation) and become > guidelines (for future code being written). That is the case of the log > levels spec: it is both a spec and a guideline. Personally I wouldn't > object if that was posted in both areas, or if the relevant pieces were > copied, once the current code has caught up, from the spec to a dev > guideline. > > In the eventlet case, it's only a set of best practices / guidelines: > there is no specific problem to solve, no catch-up plan for existing > code to implement. Only a collection of recommendations if you get to > write future eventlet-based code. Those won't start or end. Which is why > I think it should go straight to a developer doc. > Well, this whole spec arose because we found out there was existing code that was doing bad things with eventlet monkey patching that needed to be fixed. The specific problem is actually being worked concurrently with the spec because everyone involved has agreed on a solution, which became one of the guidelines in the spec. I'd be surprised if there aren't other projects that need similar changes to be in line with the new recommendations though. I'd hope that future projects will follow the guidelines, but they were actually written for the purpose of eliminating as many potential eventlet gotchas in our _current_ code as possible. Coming up with a specific list of changes needed is tough until we have agreement on the best practices though, which is why the first work item is a somewhat vague "audit and fix all the things" point. Personally, I would expect most best practice/guideline type specs to be similar. Nobody's going to take the time to write up a spec about something everyone's already doing - they're going to do it because one or a few projects have found something that works well and they think everyone should be doing it. So I think your point about most of these things moving from spec to guideline throughout their lifetime is spot on, I'm just wondering if it's worth complicating the workflow for that process. Herding the cats for something big like the log guidelines is hard enough without requiring two separate documents for the immediate work and the long-term information. That said, I agree with the points about publishing this stuff under a developer reference doc rather than specs, and if that can't be done in a single repo maybe we do have to split. I'd still prefer to keep it all in one repo though - moving a doc between directories is a lot simpler than moving it between repos (and also doesn't lose any previous discussion in Gerrit). -Ben __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
On Wed, Feb 25, 2015 at 02:54:35PM -0500, Doug Hellmann wrote: > > That leads to two questions, then: > > 1. Should we have a unified developer guide for the project? Sounds like a great idea to me, I think we should. > 2. Where should it live and how should we manage it? > I like Stefano's idea of it being under docs.openstack.org/developer > An alternative is to designate a subsection of the openstack-specs > repository for the content, as we’ve done in Oslo. In this case, > though, I think it makes more sense to create a new repository. If > there is a general agreement to go ahead with the plan, I will set > that up with a Sphinx project framework to get us started. > > Comments? > > Doug Gorka Eguileor. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
Doug Hellmann wrote: > Maybe some of the folks in the meeting who felt more strongly that it > should be a separate document can respond with their thoughts? I don't feel very strongly and could survive this landing in openstack-specs. My objection was the following: - Specs are for designing the solution and implementation plan to a specific problem. They are mainly used by developers and reviewers during implementation as a clear reference rationale for change and approved plan. Once they are fully implemented, they are kept for history purpose, not for constant reference. - Guidelines/developer doc are for all developers (old and new) to converge on best practices on topics that are not directly implemented as hacking rules. They are constantly used by everyone (not just developers/reviewers of a given feature) and never become "history". Putting guidelines doc in the middle of specs makes it a bit less discoverable imho, especially by our new developers. It's harder to determine which are still current and you should read. An "OpenStack developer doc" sounds like a much better entry point. That said, the devil is in the details, and some efforts start as specs (for existing code to catch up with the recommendation) and become guidelines (for future code being written). That is the case of the log levels spec: it is both a spec and a guideline. Personally I wouldn't object if that was posted in both areas, or if the relevant pieces were copied, once the current code has caught up, from the spec to a dev guideline. In the eventlet case, it's only a set of best practices / guidelines: there is no specific problem to solve, no catch-up plan for existing code to implement. Only a collection of recommendations if you get to write future eventlet-based code. Those won't start or end. Which is why I think it should go straight to a developer doc. -- Thierry Carrez (ttx) __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
On Wed, 2015-02-25 at 14:54 -0500, Doug Hellmann wrote: > 1. Should we have a unified developer guide for the project? Yes. Absolutely. Yes. > 2. Where should it live and how should we manage it? I think the natural destination for it would be the URL http://docs.openstack.org/developer (which should be instead named /contributor to avoid collision with developer.openstack.org) I started playing around with an entry portal for new contributors, one that would give a clear path (think a ladder) from setup dev environment to first code reviews to full on core member. Since we teach this stuff at Upstream Training, I used the timeline in the class to start assembling a table of content for a new contributor's guide https://etherpad.openstack.org/p/coherent-path-for-contributors > I believe we would benefit by having a more formal place to write down > some of our experiences in ways that make them discoverable. We have > been using the wiki for this, but it is often challenging to find > information in the wiki if you don’t generally know where to look for > it. The problem is that some stuff is in the wiki (which can be and is being improved, btw) and some other stuff is scattered around and often duplicated in project's repos. > That leads to an answer to question 2: create a new git repository to > host a Sphinx-based manual similar to what many projects already have. > We would then try to unify content from all sources where it applies > to the whole project, and we could eventually start moving some of the > wiki content into it as well. This sounds like a good approach to me already. Unless someone has better alternatives, I'd go for it. > If we decide to create the repository, we would also need to decide > how it would be managed. The rules set up for the cross-project specs > repository seems close to what we want (everyone can +1/-1; TC members > can +2/-2; the TC chair tallies the votes and uses workflow+1) [4]. Sounds good to me, at least to get started. At some point the people who care the most for this effort will emerge and maybe the TC will give the +w also to them. /stef __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
On Thu, Feb 26, 2015, at 03:55 PM, Ben Nemec wrote: > So, I'm wondering how much of this is unnecessarily splitting hairs on > what defines a cross-project spec. If you look at the currently merged > specs, they are in fact both Guidelines: > http://specs.openstack.org/openstack/openstack-specs/ That's a fair point. I was inclined to go ahead and use the existing specs repo, but I said I would start the discussion on the mailing list. Maybe some of the folks in the meeting who felt more strongly that it should be a separate document can respond with their thoughts? Doug > > Would renaming mine Eventlet Guidelines make it more palatable? :-) > > I say that somewhat tongue in cheek, but the reality is that a lot of > the specs proposed to openstack-specs are basically the same thing: > prescriptive best practices to make our projects more > consistent/robust/usable. Also, there's an implied action required for > each of them, which is to find any projects not following the guidelines > and assimilate them (resistance is futile! ;-). > > Given that, I do question the value of creating yet another > cross-project repo that people will have to watch just to house > long-lived "specs" like these. If anything, I would say that the more > limited timeframe specs should move into a cycle-specific folder like > they are in the other projects, although TBH the only ones I'm seeing > proposed so far that would meet that definition is the eventlet->[other > concurrency model] specs because if we decide to go forward with them > they will at some point be "done". All of the others I see proposed > seem to be indefinite "here's how you should be doing $SOMETHING" > documents. > > Ultimately I guess I don't care where these things end up living as long > as they exist somewhere, but splitting this repo feels like extra > bureaucracy for no tangible benefit to me. Ultimately I think I would > prefer a policies vs. cycles split in-repo like we have for Oslo over > creating another repo that will behave exactly the same way except for > the intended lifespan of the specs. > > /2 cents > > -Ben > > On 02/25/2015 01:54 PM, Doug Hellmann wrote: > > During yesterday’s cross-project meeting [1], we discussed the "Eventlet > > Best Practices” spec [2] started by bnemec. The discussion of that spec > > revolved around the question of whether our cross-project specs repository > > is the right place for this type of document that isn’t a “plan” for a > > change, and is more a reference guide. Eventually we came around to the > > idea of creating a cross-project developer guide to hold these sorts of > > materials. > > > > That leads to two questions, then: > > > > 1. Should we have a unified developer guide for the project? > > 2. Where should it live and how should we manage it? > > > > I believe we would benefit by having a more formal place to write down some > > of our experiences in ways that make them discoverable. We have been using > > the wiki for this, but it is often challenging to find information in the > > wiki if you don’t generally know where to look for it. That leads to an > > answer to question 2: create a new git repository to host a Sphinx-based > > manual similar to what many projects already have. We would then try to > > unify content from all sources where it applies to the whole project, and > > we could eventually start moving some of the wiki content into it as well. > > > > Oslo has already started moving some of our reference materials from the > > wiki into a “policy” section of the oslo-specs repository, and one benefit > > we found to using git to manage those policy documents is that we have a > > record of the discussion of the changes to the pages, and we can > > collaborate on changes through our code review system — so everyone on the > > team has a voice and can comment on the changes. It can also be a bit > > easier to do things like include sample code [3]. > > > > Right now each project has its own reference guide, with project-specific > > information in it. Not all projects are going to agree to all of the > > guidelines, but it will be useful to have the conversation about those > > points where we are doing things differently so we can learn from each > > other. > > > > If we decide to create the repository, we would also need to decide how it > > would be managed. The rules set up for the cross-project specs repository > > seems close to what we want (everyone can +1/-1; TC members can +2/-2; the > > TC chair tallies the votes and uses workflow+1) [4]. > > > > An alternative is to designate a subsection of the openstack-specs > > repository for the content, as we’ve done in Oslo. In this case, though, I > > think it makes more sense to create a new repository. If there is a general > > agreement to go ahead with the plan, I will set that up with a Sphinx > > project framework to get us started. > > > > Comments? > > > > Doug > >
Re: [openstack-dev] [all] creating a unified developer reference manual
So, I'm wondering how much of this is unnecessarily splitting hairs on what defines a cross-project spec. If you look at the currently merged specs, they are in fact both Guidelines: http://specs.openstack.org/openstack/openstack-specs/ Would renaming mine Eventlet Guidelines make it more palatable? :-) I say that somewhat tongue in cheek, but the reality is that a lot of the specs proposed to openstack-specs are basically the same thing: prescriptive best practices to make our projects more consistent/robust/usable. Also, there's an implied action required for each of them, which is to find any projects not following the guidelines and assimilate them (resistance is futile! ;-). Given that, I do question the value of creating yet another cross-project repo that people will have to watch just to house long-lived "specs" like these. If anything, I would say that the more limited timeframe specs should move into a cycle-specific folder like they are in the other projects, although TBH the only ones I'm seeing proposed so far that would meet that definition is the eventlet->[other concurrency model] specs because if we decide to go forward with them they will at some point be "done". All of the others I see proposed seem to be indefinite "here's how you should be doing $SOMETHING" documents. Ultimately I guess I don't care where these things end up living as long as they exist somewhere, but splitting this repo feels like extra bureaucracy for no tangible benefit to me. Ultimately I think I would prefer a policies vs. cycles split in-repo like we have for Oslo over creating another repo that will behave exactly the same way except for the intended lifespan of the specs. /2 cents -Ben On 02/25/2015 01:54 PM, Doug Hellmann wrote: > During yesterday’s cross-project meeting [1], we discussed the "Eventlet Best > Practices” spec [2] started by bnemec. The discussion of that spec revolved > around the question of whether our cross-project specs repository is the > right place for this type of document that isn’t a “plan” for a change, and > is more a reference guide. Eventually we came around to the idea of creating > a cross-project developer guide to hold these sorts of materials. > > That leads to two questions, then: > > 1. Should we have a unified developer guide for the project? > 2. Where should it live and how should we manage it? > > I believe we would benefit by having a more formal place to write down some > of our experiences in ways that make them discoverable. We have been using > the wiki for this, but it is often challenging to find information in the > wiki if you don’t generally know where to look for it. That leads to an > answer to question 2: create a new git repository to host a Sphinx-based > manual similar to what many projects already have. We would then try to unify > content from all sources where it applies to the whole project, and we could > eventually start moving some of the wiki content into it as well. > > Oslo has already started moving some of our reference materials from the wiki > into a “policy” section of the oslo-specs repository, and one benefit we > found to using git to manage those policy documents is that we have a record > of the discussion of the changes to the pages, and we can collaborate on > changes through our code review system — so everyone on the team has a voice > and can comment on the changes. It can also be a bit easier to do things like > include sample code [3]. > > Right now each project has its own reference guide, with project-specific > information in it. Not all projects are going to agree to all of the > guidelines, but it will be useful to have the conversation about those points > where we are doing things differently so we can learn from each other. > > If we decide to create the repository, we would also need to decide how it > would be managed. The rules set up for the cross-project specs repository > seems close to what we want (everyone can +1/-1; TC members can +2/-2; the TC > chair tallies the votes and uses workflow+1) [4]. > > An alternative is to designate a subsection of the openstack-specs repository > for the content, as we’ve done in Oslo. In this case, though, I think it > makes more sense to create a new repository. If there is a general agreement > to go ahead with the plan, I will set that up with a Sphinx project framework > to get us started. > > Comments? > > Doug > > > [1] > http://eavesdrop.openstack.org/meetings/crossproject/2015/crossproject.2015-02-24-21.03.log.html > [2] https://review.openstack.org/#/c/154642/ > [3] http://docs.openstack.org/developer/oslo.log/api/fixtures.html > [4] > http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-02-24-20.02.log.html > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsu
Re: [openstack-dev] [all] creating a unified developer reference manual
Sounds like a very good idea. Cross project development shared knowledge. Miguel Ángel Ajo On Wednesday, 25 de February de 2015 at 22:32, michael mccune wrote: > On 02/25/2015 02:54 PM, Doug Hellmann wrote: > > During yesterday’s cross-project meeting [1], we discussed the "Eventlet > > Best Practices” spec [2] started by bnemec. The discussion of that spec > > revolved around the question of whether our cross-project specs repository > > is the right place for this type of document that isn’t a “plan” for a > > change, and is more a reference guide. Eventually we came around to the > > idea of creating a cross-project developer guide to hold these sorts of > > materials. > > > > That leads to two questions, then: > > > > 1. Should we have a unified developer guide for the project? > > +1, this sounds like a fantastic idea. > > > 2. Where should it live and how should we manage it? > > i like the idea of creating a new repository, akin to the other > OpenStack manuals. i think it would be great if there was an easy way > for the individual projects to add their specific recommendations as well. > > the main downside i see to creating a new repo/manual/infra is the > project overhead. hopefully there will be enough interest that this > won't be an issue though. > > mike > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > (mailto:openstack-dev-requ...@lists.openstack.org?subject:unsubscribe) > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
On 02/25/2015 02:54 PM, Doug Hellmann wrote: During yesterday’s cross-project meeting [1], we discussed the "Eventlet Best Practices” spec [2] started by bnemec. The discussion of that spec revolved around the question of whether our cross-project specs repository is the right place for this type of document that isn’t a “plan” for a change, and is more a reference guide. Eventually we came around to the idea of creating a cross-project developer guide to hold these sorts of materials. That leads to two questions, then: 1. Should we have a unified developer guide for the project? +1, this sounds like a fantastic idea. 2. Where should it live and how should we manage it? i like the idea of creating a new repository, akin to the other OpenStack manuals. i think it would be great if there was an easy way for the individual projects to add their specific recommendations as well. the main downside i see to creating a new repo/manual/infra is the project overhead. hopefully there will be enough interest that this won't be an issue though. mike __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
On Wed, Feb 25, 2015 at 12:49 PM, Doug Hellmann wrote: > > > On Wed, Feb 25, 2015, at 03:14 PM, Joe Gordon wrote: > > On Wed, Feb 25, 2015 at 11:54 AM, Doug Hellmann > > wrote: > > > > > During yesterday’s cross-project meeting [1], we discussed the > "Eventlet > > > Best Practices” spec [2] started by bnemec. The discussion of that spec > > > revolved around the question of whether our cross-project specs > repository > > > is the right place for this type of document that isn’t a “plan” for a > > > change, and is more a reference guide. Eventually we came around to the > > > idea of creating a cross-project developer guide to hold these sorts of > > > materials. > > > > > > That leads to two questions, then: > > > > > > 1. Should we have a unified developer guide for the project? > > > 2. Where should it live and how should we manage it? > > > > > > I believe we would benefit by having a more formal place to write down > > > some of our experiences in ways that make them discoverable. We have > been > > > using the wiki for this, but it is often challenging to find > information in > > > the wiki if you don’t generally know where to look for it. That leads > to an > > > answer to question 2: create a new git repository to host a > Sphinx-based > > > manual similar to what many projects already have. We would then try to > > > unify content from all sources where it applies to the whole project, > and > > > we could eventually start moving some of the wiki content into it as > well. > > > > > > Oslo has already started moving some of our reference materials from > the > > > wiki into a “policy” section of the oslo-specs repository, and one > benefit > > > we found to using git to manage those policy documents is that we have > a > > > record of the discussion of the changes to the pages, and we can > > > collaborate on changes through our code review system — so everyone on > the > > > team has a voice and can comment on the changes. It can also be a bit > > > easier to do things like include sample code [3]. > > > > > > Right now each project has its own reference guide, with > project-specific > > > information in it. Not all projects are going to agree to all of the > > > guidelines, but it will be useful to have the conversation about those > > > points where we are doing things differently so we can learn from each > > > other. > > > > > > > I like the idea of a unified developer reference. There is a bunch of > > stuff > > in the nova devref that isn't nova specific such as: > > > > http://docs.openstack.org/developer/nova/devref/unit_tests.html > > > > As for how to manage what is project specific and what isn't. Something > > along the lines of how we do it in hacking may be nice. Each project has > > its own file that has project specific things and references the main > > hacking doc > > (https://github.com/openstack/keystone/blob/master/HACKING.rst). > > I was more interested in how we come to agree on what is global vs. what > isn't, but I definitely agree that anything deemed project-specific > should stay in the project's documentation somewhere. > As you know, doing this in Hacking has been difficult. So I don't have any good answers here, except I think there is a ton of low hanging fruit that we can tackle first. > > Doug > > > > > > > > > > > > > > > If we decide to create the repository, we would also need to decide > how it > > > would be managed. The rules set up for the cross-project specs > repository > > > seems close to what we want (everyone can +1/-1; TC members can +2/-2; > the > > > TC chair tallies the votes and uses workflow+1) [4]. > > > > > > An alternative is to designate a subsection of the openstack-specs > > > repository for the content, as we’ve done in Oslo. In this case, > though, I > > > think it makes more sense to create a new repository. If there is a > general > > > agreement to go ahead with the plan, I will set that up with a Sphinx > > > project framework to get us started. > > > > > > Comments? > > > > > > Doug > > > > > > > > > [1] > > > > http://eavesdrop.openstack.org/meetings/crossproject/2015/crossproject.2015-02-24-21.03.log.html > > > [2] https://review.openstack.org/#/c/154642/ > > > [3] http://docs.openstack.org/developer/oslo.log/api/fixtures.html > > > [4] > > > > http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-02-24-20.02.log.html > > > > __ > > > OpenStack Development Mailing List (not for usage questions) > > > Unsubscribe: > openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > > > __ > > OpenStack Development Mailing List (not for usage questions) > > Unsubscribe: > > openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
On Wed, Feb 25, 2015, at 03:14 PM, Joe Gordon wrote: > On Wed, Feb 25, 2015 at 11:54 AM, Doug Hellmann > wrote: > > > During yesterday’s cross-project meeting [1], we discussed the "Eventlet > > Best Practices” spec [2] started by bnemec. The discussion of that spec > > revolved around the question of whether our cross-project specs repository > > is the right place for this type of document that isn’t a “plan” for a > > change, and is more a reference guide. Eventually we came around to the > > idea of creating a cross-project developer guide to hold these sorts of > > materials. > > > > That leads to two questions, then: > > > > 1. Should we have a unified developer guide for the project? > > 2. Where should it live and how should we manage it? > > > > I believe we would benefit by having a more formal place to write down > > some of our experiences in ways that make them discoverable. We have been > > using the wiki for this, but it is often challenging to find information in > > the wiki if you don’t generally know where to look for it. That leads to an > > answer to question 2: create a new git repository to host a Sphinx-based > > manual similar to what many projects already have. We would then try to > > unify content from all sources where it applies to the whole project, and > > we could eventually start moving some of the wiki content into it as well. > > > > Oslo has already started moving some of our reference materials from the > > wiki into a “policy” section of the oslo-specs repository, and one benefit > > we found to using git to manage those policy documents is that we have a > > record of the discussion of the changes to the pages, and we can > > collaborate on changes through our code review system — so everyone on the > > team has a voice and can comment on the changes. It can also be a bit > > easier to do things like include sample code [3]. > > > > Right now each project has its own reference guide, with project-specific > > information in it. Not all projects are going to agree to all of the > > guidelines, but it will be useful to have the conversation about those > > points where we are doing things differently so we can learn from each > > other. > > > > I like the idea of a unified developer reference. There is a bunch of > stuff > in the nova devref that isn't nova specific such as: > > http://docs.openstack.org/developer/nova/devref/unit_tests.html > > As for how to manage what is project specific and what isn't. Something > along the lines of how we do it in hacking may be nice. Each project has > its own file that has project specific things and references the main > hacking doc > (https://github.com/openstack/keystone/blob/master/HACKING.rst). I was more interested in how we come to agree on what is global vs. what isn't, but I definitely agree that anything deemed project-specific should stay in the project's documentation somewhere. Doug > > > > > > > > If we decide to create the repository, we would also need to decide how it > > would be managed. The rules set up for the cross-project specs repository > > seems close to what we want (everyone can +1/-1; TC members can +2/-2; the > > TC chair tallies the votes and uses workflow+1) [4]. > > > > An alternative is to designate a subsection of the openstack-specs > > repository for the content, as we’ve done in Oslo. In this case, though, I > > think it makes more sense to create a new repository. If there is a general > > agreement to go ahead with the plan, I will set that up with a Sphinx > > project framework to get us started. > > > > Comments? > > > > Doug > > > > > > [1] > > http://eavesdrop.openstack.org/meetings/crossproject/2015/crossproject.2015-02-24-21.03.log.html > > [2] https://review.openstack.org/#/c/154642/ > > [3] http://docs.openstack.org/developer/oslo.log/api/fixtures.html > > [4] > > http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-02-24-20.02.log.html > > __ > > OpenStack Development Mailing List (not for usage questions) > > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: > openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [all] creating a unified developer reference manual
On Wed, Feb 25, 2015 at 11:54 AM, Doug Hellmann wrote: > During yesterday’s cross-project meeting [1], we discussed the "Eventlet > Best Practices” spec [2] started by bnemec. The discussion of that spec > revolved around the question of whether our cross-project specs repository > is the right place for this type of document that isn’t a “plan” for a > change, and is more a reference guide. Eventually we came around to the > idea of creating a cross-project developer guide to hold these sorts of > materials. > > That leads to two questions, then: > > 1. Should we have a unified developer guide for the project? > 2. Where should it live and how should we manage it? > > I believe we would benefit by having a more formal place to write down > some of our experiences in ways that make them discoverable. We have been > using the wiki for this, but it is often challenging to find information in > the wiki if you don’t generally know where to look for it. That leads to an > answer to question 2: create a new git repository to host a Sphinx-based > manual similar to what many projects already have. We would then try to > unify content from all sources where it applies to the whole project, and > we could eventually start moving some of the wiki content into it as well. > > Oslo has already started moving some of our reference materials from the > wiki into a “policy” section of the oslo-specs repository, and one benefit > we found to using git to manage those policy documents is that we have a > record of the discussion of the changes to the pages, and we can > collaborate on changes through our code review system — so everyone on the > team has a voice and can comment on the changes. It can also be a bit > easier to do things like include sample code [3]. > > Right now each project has its own reference guide, with project-specific > information in it. Not all projects are going to agree to all of the > guidelines, but it will be useful to have the conversation about those > points where we are doing things differently so we can learn from each > other. > I like the idea of a unified developer reference. There is a bunch of stuff in the nova devref that isn't nova specific such as: http://docs.openstack.org/developer/nova/devref/unit_tests.html As for how to manage what is project specific and what isn't. Something along the lines of how we do it in hacking may be nice. Each project has its own file that has project specific things and references the main hacking doc (https://github.com/openstack/keystone/blob/master/HACKING.rst). > > If we decide to create the repository, we would also need to decide how it > would be managed. The rules set up for the cross-project specs repository > seems close to what we want (everyone can +1/-1; TC members can +2/-2; the > TC chair tallies the votes and uses workflow+1) [4]. > > An alternative is to designate a subsection of the openstack-specs > repository for the content, as we’ve done in Oslo. In this case, though, I > think it makes more sense to create a new repository. If there is a general > agreement to go ahead with the plan, I will set that up with a Sphinx > project framework to get us started. > > Comments? > > Doug > > > [1] > http://eavesdrop.openstack.org/meetings/crossproject/2015/crossproject.2015-02-24-21.03.log.html > [2] https://review.openstack.org/#/c/154642/ > [3] http://docs.openstack.org/developer/oslo.log/api/fixtures.html > [4] > http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-02-24-20.02.log.html > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [all] creating a unified developer reference manual
During yesterday’s cross-project meeting [1], we discussed the "Eventlet Best Practices” spec [2] started by bnemec. The discussion of that spec revolved around the question of whether our cross-project specs repository is the right place for this type of document that isn’t a “plan” for a change, and is more a reference guide. Eventually we came around to the idea of creating a cross-project developer guide to hold these sorts of materials. That leads to two questions, then: 1. Should we have a unified developer guide for the project? 2. Where should it live and how should we manage it? I believe we would benefit by having a more formal place to write down some of our experiences in ways that make them discoverable. We have been using the wiki for this, but it is often challenging to find information in the wiki if you don’t generally know where to look for it. That leads to an answer to question 2: create a new git repository to host a Sphinx-based manual similar to what many projects already have. We would then try to unify content from all sources where it applies to the whole project, and we could eventually start moving some of the wiki content into it as well. Oslo has already started moving some of our reference materials from the wiki into a “policy” section of the oslo-specs repository, and one benefit we found to using git to manage those policy documents is that we have a record of the discussion of the changes to the pages, and we can collaborate on changes through our code review system — so everyone on the team has a voice and can comment on the changes. It can also be a bit easier to do things like include sample code [3]. Right now each project has its own reference guide, with project-specific information in it. Not all projects are going to agree to all of the guidelines, but it will be useful to have the conversation about those points where we are doing things differently so we can learn from each other. If we decide to create the repository, we would also need to decide how it would be managed. The rules set up for the cross-project specs repository seems close to what we want (everyone can +1/-1; TC members can +2/-2; the TC chair tallies the votes and uses workflow+1) [4]. An alternative is to designate a subsection of the openstack-specs repository for the content, as we’ve done in Oslo. In this case, though, I think it makes more sense to create a new repository. If there is a general agreement to go ahead with the plan, I will set that up with a Sphinx project framework to get us started. Comments? Doug [1] http://eavesdrop.openstack.org/meetings/crossproject/2015/crossproject.2015-02-24-21.03.log.html [2] https://review.openstack.org/#/c/154642/ [3] http://docs.openstack.org/developer/oslo.log/api/fixtures.html [4] http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-02-24-20.02.log.html __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
