Re: [geonode] Project policies
- From:
- David Winslow
- Date:
- 2010-07-08 @ 19:05
On 07/08/2010 03:00 AM, Andreas Hocevar wrote:
> Hi,
>
> see my comments inline.
>
> On Jul 7, 2010, at 18:32 , David Winslow wrote:
>
>
>> Hey all,
>>
>> Thus far the GeoNode has been fairly laxly managed with regard to
commit review, standards enforcement, and basically anything that looks
like watching what goes into the repository. I think as we approach 1.0
we should revisit these issues to help facilitate participation from
"non-core" contributors.
>>
>> recap
>> Just to review, GeoNode's source tree can be thought of as three or
four different components:
>>
>> * A Django application
>> * Some JavaScript and CSS to decorate the Django application. It's
Serious Stuff and not just a subproject of the web frontend.
>> * A collection of GeoServer extensions to support the Django application.
>> * And a bunch of bubblegum and python scripts to stitch it all together.
>>
>> Right now Ariel, Ivan, Seb, Andreas, Gabriel, and myself have free
commit access to all of that (and it's all in one git repo so restricting
access partwise would require restructuring things).
>>
>> We also maintain a few static resources (sample datadir for GeoServer,
GeoNetwork with custom schema preinstalled) and a few git-svn mirrors of
"upstream" projects (OpenLayers, GeoExt, gxp). Gabriel unofficially
maintains the former, Andreas maintains the latter, and I have access to
step in and update both in case they are unavailable or whatever.
>>
>> questions
>> These are some things that other projects have explicit policies for
(which is nice in avoiding partiality in some potentially touchy
decisions)
>>
>> How do you prove you are trustworthy enough to commit directly to the
main repository?
>>
> As in GeoServer, most other projects require you to submit several
quality patches before you can become a core committer.
>
> For core committers, I'd say we should enforce that every change
requires a ticket. The commit comment has to link to the ticket, and when
closing the ticket a link to the committed changeset has to be added to
the ticket. We should start with this as of now.
>
> As soon as possible, we should start requiring unit tests. Selenium has
been brought up, which is great, but it's also got quite a learning curve
and creating tests is somewhat time consuming. Personally, I'm familiar
with TestAnotherWay, which is not great, but does its job well for
JavaScript stuff - as long as there is not too much UI to test.
>
> In OpenLayers, unit test coverage used to grow with every ticket/patch.
So one way to do it would be to start requiring unit tests at some point,
and from that point on every change needs to be accompanied by unit tests.
>
>
>> How do you propose changes if you haven't proved that yet (and maybe
never will)?
>>
> My proposal for GeoNode: Patches from community members without commit
access to the main repository require a patch, which is attached to a
ticket. Discussion of the change in the mailing list with a reference to
the ticket is encouraged. If a core committer is convinced, after several
patches, that they show a deep understanding of the code base and
architecture, the committer can propose to give the contributor core
commit access. We need to decide on a voting process for that.
>
>
>> What criteria are sufficient to reject a patch?
>>
> This will be much easier when we have unit tests. Patches that make unit
tests fail will be rejected. Coding style is also a criteria. And if we
keep the concept of domain experts (e.g. myself for the JavaScript part),
domain experts usually can judge by their project knowledge if the patch
does something that does not fit. If it does not fit, the reason has to be
explained on the ticket.
>
>
>> How are major changes (large refactorings, changes to the interface
between components, big new features) handled?
>>
> Big new features that don't affect existing code can go in with the
lightweight process discussed above. For big changes to existing code:
discussion on the mailing list, tickets with patches or a separate branch
on github. If the change involves changes to more than one domain (e.g.
Django and JavaScript), core committers of all affected domains need to
review the patch/branch before it can go into the main repo.
>
> All these questions need to be answered, and the processes described, on
a community/process page on the project wiki.
>
> Another thing that is important: if OpenPlans is to be the copyright
holder, we will need contributor license agreements from all contributors
and committers.
>
> My 2¢,
> Andreas.
>
>
>> case study
>> In GeoServer, which is both fairly familiar to me and a good example of
a project with intentionally distributed decision making, the answers are:
>>
>> * Prove you are trustworthy by: Get at least two accepted patches into
SVN, and receive a nomination from a current committer. Two plus votes
are also required, and any committer can veto.
>>
>> * Propose changes by: Report an issue on GeoServer's JIRA setup.
Discussion on the mailing list beforehand, and attaching a patch both
encouraged but optional. Committers are expected to go through JIRA as
well to help track what improvements go into each release.
>>
>> * Reject a patch: There are a number of guidelines; style guidelines
about how to indent code and such, design guidelines about how geoserver
code should interact with geotools code, etc. GeoServer is also divided
up into several modules each of which has a "maintainer" who reviews
patches and can dismiss a patch for any reason he sees fit.
>>
>> * Large refactorings or new features require a GSIP (GeoServer
Improvement Proposal) before they can be committed to SVN. These are
voted on by the PSC after a "review and revise" period that lasts a few
days.
>>
>> current status
>> For us right now, the policy is something like:
>>
>> * Prove you are tsustworthy by being around early in the project history
>> * Propose changes by: discussion on the mailing list. We don't have a
lot of changes coming in from non-committers.
>> * Reject a patch: hasn't come up yet because everyone working on
GeoNode right now has commit rights.
>> * large refactorings or new features - git branching is encouraged but
not enforced.
>>
>> bottom line
>> So what should the geonode policy be? some goals of the policy would be
>> - guide arbitration on third party (and 'core') changes
>> - maintain some level of code quality in 'master'
>> - facilitate production of especially-well-tested releases (compared to
master at an arbitrary point in time)
>> - facilitate development of custom features/extensions to the geonode
>>
>> --
>> David Winslow
>> OpenGeo - http://opengeo.org/
>>
I started a page on etherplans (a clone of Etherpad run by OpenPlans) to
follow this discussion and work on a draft of the wiki page. I think
it's easier to deal with than interleaving comments in emails like this,
plus, you know, it's awesome for collaboratively drafting text.
link: http://etherplans.org/geonode-commit-policy
--
David Winslow
OpenGeo - http://opengeo.org/
Re: [geonode] Project policies
- From:
- Sebastian Benthall
- Date:
- 2010-07-08 @ 13:30
One thing I can think of right off the bat that is comments on the Python
stuff in particular. I think it would be good to adopt a standard for that
and try to stick to it.
On Thu, Jul 8, 2010 at 3:00 AM, Andreas Hocevar <ahocevar@opengeo.org>wrote:
> Hi,
>
> see my comments inline.
>
> On Jul 7, 2010, at 18:32 , David Winslow wrote:
>
> > Hey all,
> >
> > Thus far the GeoNode has been fairly laxly managed with regard to commit
> review, standards enforcement, and basically anything that looks like
> watching what goes into the repository. I think as we approach 1.0 we
> should revisit these issues to help facilitate participation from "non-core"
> contributors.
> >
> > recap
> > Just to review, GeoNode's source tree can be thought of as three or four
> different components:
> >
> > * A Django application
> > * Some JavaScript and CSS to decorate the Django application. It's
> Serious Stuff and not just a subproject of the web frontend.
> > * A collection of GeoServer extensions to support the Django application.
> > * And a bunch of bubblegum and python scripts to stitch it all together.
> >
> > Right now Ariel, Ivan, Seb, Andreas, Gabriel, and myself have free commit
> access to all of that (and it's all in one git repo so restricting access
> partwise would require restructuring things).
> >
> > We also maintain a few static resources (sample datadir for GeoServer,
> GeoNetwork with custom schema preinstalled) and a few git-svn mirrors of
> "upstream" projects (OpenLayers, GeoExt, gxp). Gabriel unofficially
> maintains the former, Andreas maintains the latter, and I have access to
> step in and update both in case they are unavailable or whatever.
> >
> > questions
> > These are some things that other projects have explicit policies for
> (which is nice in avoiding partiality in some potentially touchy decisions)
> >
> > How do you prove you are trustworthy enough to commit directly to the
> main repository?
>
> As in GeoServer, most other projects require you to submit several quality
> patches before you can become a core committer.
>
> For core committers, I'd say we should enforce that every change requires a
> ticket. The commit comment has to link to the ticket, and when closing the
> ticket a link to the committed changeset has to be added to the ticket. We
> should start with this as of now.
>
> As soon as possible, we should start requiring unit tests. Selenium has
> been brought up, which is great, but it's also got quite a learning curve
> and creating tests is somewhat time consuming. Personally, I'm familiar with
> TestAnotherWay, which is not great, but does its job well for JavaScript
> stuff - as long as there is not too much UI to test.
>
> In OpenLayers, unit test coverage used to grow with every ticket/patch. So
> one way to do it would be to start requiring unit tests at some point, and
> from that point on every change needs to be accompanied by unit tests.
>
> > How do you propose changes if you haven't proved that yet (and maybe
> never will)?
>
> My proposal for GeoNode: Patches from community members without commit
> access to the main repository require a patch, which is attached to a
> ticket. Discussion of the change in the mailing list with a reference to the
> ticket is encouraged. If a core committer is convinced, after several
> patches, that they show a deep understanding of the code base and
> architecture, the committer can propose to give the contributor core commit
> access. We need to decide on a voting process for that.
>
> > What criteria are sufficient to reject a patch?
>
> This will be much easier when we have unit tests. Patches that make unit
> tests fail will be rejected. Coding style is also a criteria. And if we keep
> the concept of domain experts (e.g. myself for the JavaScript part), domain
> experts usually can judge by their project knowledge if the patch does
> something that does not fit. If it does not fit, the reason has to be
> explained on the ticket.
>
> > How are major changes (large refactorings, changes to the interface
> between components, big new features) handled?
>
> Big new features that don't affect existing code can go in with the
> lightweight process discussed above. For big changes to existing code:
> discussion on the mailing list, tickets with patches or a separate branch on
> github. If the change involves changes to more than one domain (e.g. Django
> and JavaScript), core committers of all affected domains need to review the
> patch/branch before it can go into the main repo.
>
> All these questions need to be answered, and the processes described, on a
> community/process page on the project wiki.
>
> Another thing that is important: if OpenPlans is to be the copyright
> holder, we will need contributor license agreements from all contributors
> and committers.
>
> My 2¢,
> Andreas.
>
> >
> > case study
> > In GeoServer, which is both fairly familiar to me and a good example of a
> project with intentionally distributed decision making, the answers are:
> >
> > * Prove you are trustworthy by: Get at least two accepted patches into
> SVN, and receive a nomination from a current committer. Two plus votes are
> also required, and any committer can veto.
> >
> > * Propose changes by: Report an issue on GeoServer's JIRA setup.
> Discussion on the mailing list beforehand, and attaching a patch both
> encouraged but optional. Committers are expected to go through JIRA as well
> to help track what improvements go into each release.
> >
> > * Reject a patch: There are a number of guidelines; style guidelines
> about how to indent code and such, design guidelines about how geoserver
> code should interact with geotools code, etc. GeoServer is also divided up
> into several modules each of which has a "maintainer" who reviews patches
> and can dismiss a patch for any reason he sees fit.
> >
> > * Large refactorings or new features require a GSIP (GeoServer
> Improvement Proposal) before they can be committed to SVN. These are voted
> on by the PSC after a "review and revise" period that lasts a few days.
> >
> > current status
> > For us right now, the policy is something like:
> >
> > * Prove you are tsustworthy by being around early in the project history
> > * Propose changes by: discussion on the mailing list. We don't have a
> lot of changes coming in from non-committers.
> > * Reject a patch: hasn't come up yet because everyone working on GeoNode
> right now has commit rights.
> > * large refactorings or new features - git branching is encouraged but
> not enforced.
> >
> > bottom line
> > So what should the geonode policy be? some goals of the policy would be
> > - guide arbitration on third party (and 'core') changes
> > - maintain some level of code quality in 'master'
> > - facilitate production of especially-well-tested releases (compared to
> master at an arbitrary point in time)
> > - facilitate development of custom features/extensions to the geonode
> >
> > --
> > David Winslow
> > OpenGeo - http://opengeo.org/
>
> --
> Andreas Hocevar
> OpenGeo - http://opengeo.org/
> Expert service straight from the developers.
>
>
--
Sebastian Benthall
OpenGeo - http://opengeo.org
Re: [geonode] Project policies
- From:
- David Winslow
- Date:
- 2010-07-08 @ 18:24
On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
> As soon as possible, we should start requiring unit tests. Selenium
> has been brought up, which is great, but it's also got quite a
> learning curve and creating tests is somewhat time consuming.
> Personally, I'm familiar with TestAnotherWay, which is not great, but
> does its job well for JavaScript stuff - as long as there is not too
> much UI to test.
>
> In OpenLayers, unit test coverage used to grow with every
> ticket/patch. So one way to do it would be to start requiring unit
> tests at some point, and from that point on every change needs to be
> accompanied by unit tests.
>
Yes, unit tests are good. Let's break off a thread to discuss them
independently of commit policies.
I think the last time we brought this up we decided that automated
testing of GUIs is hard and doubly so when those GUIs are made out of
HTML and CSS and being tested through Selenium. Additionally, GeoNode's
JavaScript is mostly GUIs built on top of frameworks that wrap data
access and such, so there wasn't a ton of perceived benefit, and we
opted to rely on our weekly deployments and keen-eyed development team
to catch bugs instead of trying to automate it.
However, the other modules are stronger in terms of unit testing
(except, oops, the Django tests rely on consistent UUIDs across builds.
Need to look into that.) The GeoServer module has decent coverage
(actually, we have a coverage meter hooked up to it.... 74% line and 57%
branch coverage)
So, we could go ahead and institute this policy on the Python and Java
sections of the project if folks want. I could go on a coverage spree
(man do I love metrics) and get things up to a decent level of coverage
on the python side, and then yell at people when they bring it down.
That does leave the question of which JavaScript framework to use. (And
I guess we can use a couple, if we want to go with Test.Anotherway for
the less graphical stuff and Selenium when macro recording seems like
the way to go.)
*recap* (I did ask a couple of questions in there :))
* Should we start requiring tests in commits immediately for the
portions of the code with already-established test frameworks?
* If not, when?
* What test framework should we use for JavaScript?
* Any other thoughts on the matter?
--
David Winslow
OpenGeo - http://opengeo.org/
Re: [geonode] Project policies
- From:
- Andreas Hocevar
- Date:
- 2010-07-14 @ 13:00
On Jul 8, 2010, at 20:24 , David Winslow wrote:
> On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
>> As soon as possible, we should start requiring unit tests. Selenium has
been brought up, which is great, but it's also got quite a learning curve
and creating tests is somewhat time consuming. Personally, I'm familiar
with TestAnotherWay, which is not great, but does its job well for
JavaScript stuff - as long as there is not too much UI to test.
>>
>> In OpenLayers, unit test coverage used to grow with every ticket/patch.
So one way to do it would be to start requiring unit tests at some point,
and from that point on every change needs to be accompanied by unit tests.
>>
> Yes, unit tests are good. Let's break off a thread to discuss them
independently of commit policies.
>
> I think the last time we brought this up we decided that automated
testing of GUIs is hard and doubly so when those GUIs are made out of HTML
and CSS and being tested through Selenium. Additionally, GeoNode's
JavaScript is mostly GUIs built on top of frameworks that wrap data access
and such, so there wasn't a ton of perceived benefit, and we opted to rely
on our weekly deployments and keen-eyed development team to catch bugs
instead of trying to automate it.
>
> However, the other modules are stronger in terms of unit testing
(except, oops, the Django tests rely on consistent UUIDs across builds.
Need to look into that.) The GeoServer module has decent coverage
(actually, we have a coverage meter hooked up to it.... 74% line and 57%
branch coverage)
>
> So, we could go ahead and institute this policy on the Python and Java
sections of the project if folks want. I could go on a coverage spree
(man do I love metrics) and get things up to a decent level of coverage on
the python side, and then yell at people when they bring it down.
>
> That does leave the question of which JavaScript framework to use. (And
I guess we can use a couple, if we want to go with Test.Anotherway for the
less graphical stuff and Selenium when macro recording seems like the way
to go.)
>
> recap (I did ask a couple of questions in there :))
> * Should we start requiring tests in commits immediately for the
portions of the code with already-established test frameworks?
> * If not, when?
> * What test framework should we use for JavaScript?
> * Any other thoughts on the matter?
I added these points to the etherpad
(http://etherplans.org/geonode-commit-policy), with notes from myself.
Regards,
Andreas.
--
Andreas Hocevar
OpenGeo - http://opengeo.org/
Expert service straight from the developers.
Re: [geonode] Project policies
- From:
- Sebastian Benthall
- Date:
- 2010-07-08 @ 19:10
*recap* (I did ask a couple of questions in there :))
> * Should we start requiring tests in commits immediately for the portions
> of the code with already-established test frameworks?
>
In my opinion, no. I think getting feature-complete for the 1.0beta release
is more important.
I don't see any efficiency gain in the short term for this.
> * If not, when?
>
Two natural options:
* After the 1.0beta release, before the 1.0 release. On the plus side this
means we could systematically make tests for bugs fixed during the beta
testing period. On the minus side, that slows down the 1.0 release.
* Beginning with post 1.0 development. More specifically, on branches that
deal with post 1.0 features and integration.
I don't have a preference either way.
--
Sebastian Benthall
OpenGeo - http://opengeo.org
Re: [geonode] Project policies
- From:
- David Winslow
- Date:
- 2010-07-08 @ 14:43
On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
> One thing I can think of right off the bat that is comments on the
> Python stuff in particular. I think it would be good to adopt a
> standard for that and try to stick to it.
>
I'm not sure I understood this; it is a vague response to a long email.
Are you saying that we should have some coding guidelines for patches to
the Python code that stipulate comment formatting?
Each language has some documented coding guidelines (with varying
degrees of officialness) we could crib off of if we want to discuss
formatting in a specific way:
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
http://www.python.org/dev/peps/pep-0008/
http://javascript.crockford.com/style1.html
Or we could look to the style guidelines of a closely related project:
http://docs.codehaus.org/display/GEOT/5.1.1+Coding+Conventions
http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
http://trac.openlayers.org/wiki/CodingStandards
Along these lines, I'd also be interested in having some browsable API
documentation once dev.geonode.org is available to us for such things.
A certain level of documentation coverage could be another factor in
patch acceptability.
--
David Winslow
OpenGeo - http://opengeo.org/
Re: [geonode] Project policies
- From:
- Sebastian Benthall
- Date:
- 2010-07-08 @ 19:00
On Thu, Jul 8, 2010 at 10:43 AM, David Winslow <dwinslow@opengeo.org> wrote:
> On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
>
>> One thing I can think of right off the bat that is comments on the Python
>> stuff in particular. I think it would be good to adopt a standard for that
>> and try to stick to it.
>>
>> I'm not sure I understood this; it is a vague response to a long email.
> Are you saying that we should have some coding guidelines for patches to
> the Python code that stipulate comment formatting?
>
Yes. Precisely.
> http://docs.codehaus.org/display/GEOT/5.1.1+Coding+Conventions
> http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
> http://trac.openlayers.org/wiki/CodingStandards
Yes. The reason why I mentioned Python specifically was because I thought
we had more or less de facto had the OpenLayers commenting standards for the
JavaScript (though I suppose we should decide whether we should use those or
the Ext ones, which if I recall correctly are different in order to support
API doc generation from the restructured text comments) and (I had assumed)
the GeoServer standards for the GeoServer-y parts.
Adopting the Django coding style for the Python bits sounds like a great
idea for me.
I notice that it though it provides something of a style guide for
docstrings, though, it doesn't say much more than "use action words." I
guess that's better than nothing. We could go with that and then adjust
later if its not sufficient.
Along these lines, I'd also be interested in having some browsable API
> documentation once dev.geonode.org is available to us for such things. A
> certain level of documentation coverage could be another factor in patch
> acceptability.
>
>
> --
> David Winslow
> OpenGeo - http://opengeo.org/
>
--
Sebastian Benthall
OpenGeo - http://opengeo.org
Re: [geonode] Project policies
- From:
- David Winslow
- Date:
- 2010-07-08 @ 20:50
http://www.python.org/dev/peps/pep-0257/ for content guidelines, docs
for whatever autodoc system we're using for markup (sphinx uses rst,
epydoc has its own thing)
-d
On 07/08/2010 03:00 PM, Sebastian Benthall wrote:
> On Thu, Jul 8, 2010 at 10:43 AM, David Winslow <dwinslow@opengeo.org
> <mailto:dwinslow@opengeo.org>> wrote:
>
> On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
>
> One thing I can think of right off the bat that is comments on
> the Python stuff in particular. I think it would be good to
> adopt a standard for that and try to stick to it.
>
> I'm not sure I understood this; it is a vague response to a long
> email. Are you saying that we should have some coding guidelines
> for patches to the Python code that stipulate comment formatting?
>
>
> Yes. Precisely.
>
> http://docs.codehaus.org/display/GEOT/5.1.1+Coding+Conventions
> http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
> http://trac.openlayers.org/wiki/CodingStandards
>
>
> Yes. The reason why I mentioned Python specifically was because I
> thought we had more or less de facto had the OpenLayers commenting
> standards for the JavaScript (though I suppose we should decide
> whether we should use those or the Ext ones, which if I recall
> correctly are different in order to support API doc generation from
> the restructured text comments) and (I had assumed) the GeoServer
> standards for the GeoServer-y parts.
>
> Adopting the Django coding style for the Python bits sounds like a
> great idea for me.
>
> I notice that it though it provides something of a style guide for
> docstrings, though, it doesn't say much more than "use action words."
> I guess that's better than nothing. We could go with that and then
> adjust later if its not sufficient.
>
> Along these lines, I'd also be interested in having some browsable
> API documentation once dev.geonode.org <http://dev.geonode.org> is
> available to us for such things. A certain level of documentation
> coverage could be another factor in patch acceptability.
>
>
> --
> David Winslow
> OpenGeo - http://opengeo.org/
>
>
>
>
> --
> Sebastian Benthall
> OpenGeo - http://opengeo.org
>
Re: [geonode] Project policies
- From:
- David Winslow
- Date:
- 2010-07-08 @ 19:06
so you're actually talking about formatting comments for a documentation
extractor like Javadoc/epydoc/naturaldocs?
-d
On 07/08/2010 03:00 PM, Sebastian Benthall wrote:
> On Thu, Jul 8, 2010 at 10:43 AM, David Winslow <dwinslow@opengeo.org
> <mailto:dwinslow@opengeo.org>> wrote:
>
> On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
>
> One thing I can think of right off the bat that is comments on
> the Python stuff in particular. I think it would be good to
> adopt a standard for that and try to stick to it.
>
> I'm not sure I understood this; it is a vague response to a long
> email. Are you saying that we should have some coding guidelines
> for patches to the Python code that stipulate comment formatting?
>
>
> Yes. Precisely.
>
> http://docs.codehaus.org/display/GEOT/5.1.1+Coding+Conventions
> http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
> http://trac.openlayers.org/wiki/CodingStandards
>
>
> Yes. The reason why I mentioned Python specifically was because I
> thought we had more or less de facto had the OpenLayers commenting
> standards for the JavaScript (though I suppose we should decide
> whether we should use those or the Ext ones, which if I recall
> correctly are different in order to support API doc generation from
> the restructured text comments) and (I had assumed) the GeoServer
> standards for the GeoServer-y parts.
>
> Adopting the Django coding style for the Python bits sounds like a
> great idea for me.
>
> I notice that it though it provides something of a style guide for
> docstrings, though, it doesn't say much more than "use action words."
> I guess that's better than nothing. We could go with that and then
> adjust later if its not sufficient.
>
> Along these lines, I'd also be interested in having some browsable
> API documentation once dev.geonode.org <http://dev.geonode.org> is
> available to us for such things. A certain level of documentation
> coverage could be another factor in patch acceptability.
>
>
> --
> David Winslow
> OpenGeo - http://opengeo.org/
>
>
>
>
> --
> Sebastian Benthall
> OpenGeo - http://opengeo.org
>
Re: [geonode] Project policies
- From:
- Sebastian Benthall
- Date:
- 2010-07-08 @ 19:15
No, I was actually talking about Python comments more generally.
However, it would be a good idea probably to choose between either the
OpenLayers or Ext coding guidelines. Documentation extraction is one issue
to think about for those.
On Thu, Jul 8, 2010 at 3:06 PM, David Winslow <dwinslow@opengeo.org> wrote:
> so you're actually talking about formatting comments for a documentation
> extractor like Javadoc/epydoc/naturaldocs?
>
> -d
>
>
> On 07/08/2010 03:00 PM, Sebastian Benthall wrote:
>
> On Thu, Jul 8, 2010 at 10:43 AM, David Winslow <dwinslow@opengeo.org>wrote:
>
>> On 07/08/2010 09:30 AM, Sebastian Benthall wrote:
>>
>>> One thing I can think of right off the bat that is comments on the Python
>>> stuff in particular. I think it would be good to adopt a standard for that
>>> and try to stick to it.
>>>
>>> I'm not sure I understood this; it is a vague response to a long email.
>> Are you saying that we should have some coding guidelines for patches to
>> the Python code that stipulate comment formatting?
>>
>
> Yes. Precisely.
>
>
>> http://docs.codehaus.org/display/GEOT/5.1.1+Coding+Conventions
>> http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style
>> http://trac.openlayers.org/wiki/CodingStandards
>
>
> Yes. The reason why I mentioned Python specifically was because I
> thought we had more or less de facto had the OpenLayers commenting standards
> for the JavaScript (though I suppose we should decide whether we should use
> those or the Ext ones, which if I recall correctly are different in order to
> support API doc generation from the restructured text comments) and (I had
> assumed) the GeoServer standards for the GeoServer-y parts.
>
> Adopting the Django coding style for the Python bits sounds like a great
> idea for me.
>
> I notice that it though it provides something of a style guide for
> docstrings, though, it doesn't say much more than "use action words." I
> guess that's better than nothing. We could go with that and then adjust
> later if its not sufficient.
>
> Along these lines, I'd also be interested in having some browsable API
>> documentation once dev.geonode.org is available to us for such things. A
>> certain level of documentation coverage could be another factor in patch
>> acceptability.
>>
>>
>> --
>> David Winslow
>> OpenGeo - http://opengeo.org/
>>
>
>
>
> --
> Sebastian Benthall
> OpenGeo - http://opengeo.org
>
>
>
--
Sebastian Benthall
OpenGeo - http://opengeo.org