librelist archives

« back to archive

initial planning

initial planning

From:
Chris Jerdonek
Date:
2011-11-27 @ 01:01
Here are two things that I think would be worth discussing initially:

(1) Should we process all outstanding pull requests chronologically
before we move to new ones, or should we be more flexible and do what
we care more about now?
(2) How strictly should we maintain backwards compatibility in the
early stages?  For example, should we preserve even "unintended"
existing behavior, and should we preserve all parts of the API (e.g.
all methods whose names don't begin with an underscore) -- even those
parts of the API that may only have been intended for use within
pystache itself?

--Chris

Re: [pystache] initial planning

From:
Tim Kersten
Date:
2011-11-29 @ 03:53
On Sun, Nov 27, 2011 at 01:01, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
> Here are two things that I think would be worth discussing initially:
>
> (1) Should we process all outstanding pull requests chronologically
> before we move to new ones, or should we be more flexible and do what
> we care more about now?

Good question :)

I don't have any experience in heading up open source projects so I'm
not sure about the pros or cons of either approach. If I had to guess,
doing this in chronological order may be most beneficial from a
community building point of view, showing that A) no preference is
given to any one particular person, and B) Respect anyone who makes an
effort to contribute. (This might help avoid the long elitest effect
from taking hold. i.e.
http://www.michele.me/blog/archives/2006/01/is-the-open-source-community-elitist/
)
On the other, doing what you care about most keeps you interested in
the project which is also beneficial to the project.

In summary, in my personal opinion, chronological order would have my
vote, though I'm not apposed to either.

> (2) How strictly should we maintain backwards compatibility in the
> early stages?  For example, should we preserve even "unintended"
> existing behavior, and should we preserve all parts of the API (e.g.
> all methods whose names don't begin with an underscore) -- even those
> parts of the API that may only have been intended for use within
> pystache itself?

I like the idea of semantic versioning (http://semver.org/). It's
obviously nice to preserve as much of any API but at the stage at
which pystache is currently at, I suspect we'd be tying our hands
behind our backs if we didn't give ourselves the flexibility to change
the private parts of the API. Perhaps the best approach here is to
document the desired public API and behavior clarified, and other
"unintended" gets changed as needed to progress the project.

Again, I'm just throwing this out there from my own perspective and am
open to weighing up the merits of an entirely different approach. What
do you think?

As a side note, between work/family/kids, I may not always get to
reply as promptly as I'd like.

Re: [pystache] initial planning

From:
Chris Jerdonek
Date:
2011-11-29 @ 04:46
On Mon, Nov 28, 2011 at 7:53 PM, Tim Kersten <tim@io41.com> wrote:
> On Sun, Nov 27, 2011 at 01:01, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
>>
>> (1) Should we process all outstanding pull requests chronologically
>> before we move to new ones, or should we be more flexible and do what
>> we care more about now?
>
> I don't have any experience in heading up open source projects so I'm
> not sure about the pros or cons of either approach. If I had to guess,
> doing this in chronological order may be most beneficial from a
> community building point of view, showing that A) no preference is
> given to any one particular person, and B) Respect anyone who makes an
> effort to contribute. (This might help avoid the long elitest effect
> from taking hold. i.e.
> 
http://www.michele.me/blog/archives/2006/01/is-the-open-source-community-elitist/
> )
> On the other, doing what you care about most keeps you interested in
> the project which is also beneficial to the project.
>
> In summary, in my personal opinion, chronological order would have my
> vote, though I'm not apposed to either.

Good summary of pros and cons.  Another pro for chronological order is
that the oldest requests may become even harder to merge the longer we
wait (though this will in some sense be true of all requests).  I was
thinking that maybe we could take a hybrid approach where we evaluate
each request in chronological order -- taking into account things like
ease or difficulty, and whether acting on it later could become
significantly easier because of anticipated refactorings, etc.  And
then act on the request based on the evaluation.  In any case, there
would be at least some discussion at each point along the way.

We probably also shouldn't rule out the possibility that other work
could be going on in parallel by others, e.g. adding a test harness
against the spec.

My only somewhat strong feeling is that we don't put a barrier in
place before we can start acting on requests, e.g. requiring that we
have a test harness against the spec in place and that passes before
we can start or that our public API be fully documented, etc.


>> (2) How strictly should we maintain backwards compatibility in the
>> early stages?  For example, should we preserve even "unintended"
>> existing behavior, and should we preserve all parts of the API (e.g.
>> all methods whose names don't begin with an underscore) -- even those
>> parts of the API that may only have been intended for use within
>> pystache itself?
>
> I like the idea of semantic versioning (http://semver.org/). It's
> obviously nice to preserve as much of any API but at the stage at
> which pystache is currently at, I suspect we'd be tying our hands
> behind our backs if we didn't give ourselves the flexibility to change
> the private parts of the API. Perhaps the best approach here is to
> document the desired public API and behavior clarified, and other
> "unintended" gets changed as needed to progress the project.

This sounds good and something to work towards.  For now, I think the
unit tests are perhaps the closest thing we have to an API (in
conjunction with the mustache(5) manual).  We can start fleshing out
the API more fully in the docstrings as we work on other stuff.  And
as above, we should of course raise for discussion any potential
breaking changes that we're not sure about.


> As a side note, between work/family/kids, I may not always get to
> reply as promptly as I'd like.

Good to know.  No rush.. :)

--Chris

Re: [pystache] initial planning

From:
Tim Kersten
Date:
2011-11-29 @ 10:33
On Tue, Nov 29, 2011 at 04:46, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
> On Mon, Nov 28, 2011 at 7:53 PM, Tim Kersten <tim@io41.com> wrote:
>> On Sun, Nov 27, 2011 at 01:01, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
>>>
>>> (1) Should we process all outstanding pull requests chronologically
>>> before we move to new ones, or should we be more flexible and do what
>>> we care more about now?
>>
>> I don't have any experience in heading up open source projects so I'm
>> not sure about the pros or cons of either approach. If I had to guess,
>> doing this in chronological order may be most beneficial from a
>> community building point of view, showing that A) no preference is
>> given to any one particular person, and B) Respect anyone who makes an
>> effort to contribute. (This might help avoid the long elitest effect
>> from taking hold. i.e.
>> 
http://www.michele.me/blog/archives/2006/01/is-the-open-source-community-elitist/
>> )
>> On the other, doing what you care about most keeps you interested in
>> the project which is also beneficial to the project.
>>
>> In summary, in my personal opinion, chronological order would have my
>> vote, though I'm not apposed to either.
>
> Good summary of pros and cons.  Another pro for chronological order is
> that the oldest requests may become even harder to merge the longer we
> wait (though this will in some sense be true of all requests).  I was
> thinking that maybe we could take a hybrid approach where we evaluate
> each request in chronological order -- taking into account things like
> ease or difficulty, and whether acting on it later could become
> significantly easier because of anticipated refactorings, etc.  And
> then act on the request based on the evaluation.  In any case, there
> would be at least some discussion at each point along the way.

That make sense, I like it. I would say let's start reviewing these as
you suggested, and if you and I and anyone else who'd like to weigh in
on any particular pull request are in agreement, we accept it.

> We probably also shouldn't rule out the possibility that other work
> could be going on in parallel by others, e.g. adding a test harness
> against the spec.

Not for right now: I'm interested in adding a test harness to the
development branch as soon as possible so I'll take a look at work
done on this and merge as appropriate. On a related note, I'd like to
see pystache getting tested for these against 2.6, 2.7, 3.2 on the
various cpython supported platforms, and pypy too, though I think
we're a bit away from that becoming practical yet.

> My only somewhat strong feeling is that we don't put a barrier in
> place before we can start acting on requests, e.g. requiring that we
> have a test harness against the spec in place and that passes before
> we can start or that our public API be fully documented, etc.

Good point. Besides, the current version is < 1.0, so to quote the
Semantic Version Specification:

> Major version zero (0.y.z) is for initial development. Anything may
> change at any time. The public API should not be considered stable.

With this in mind, I'd like to propose we officially adopt
http://semver.org/ for pystache. Thoughts?


>>> (2) How strictly should we maintain backwards compatibility in the
>>> early stages?  For example, should we preserve even "unintended"
>>> existing behavior, and should we preserve all parts of the API (e.g.
>>> all methods whose names don't begin with an underscore) -- even those
>>> parts of the API that may only have been intended for use within
>>> pystache itself?
>>
>> I like the idea of semantic versioning (http://semver.org/). It's
>> obviously nice to preserve as much of any API but at the stage at
>> which pystache is currently at, I suspect we'd be tying our hands
>> behind our backs if we didn't give ourselves the flexibility to change
>> the private parts of the API. Perhaps the best approach here is to
>> document the desired public API and behavior clarified, and other
>> "unintended" gets changed as needed to progress the project.
>
> This sounds good and something to work towards.  For now, I think the
> unit tests are perhaps the closest thing we have to an API (in
> conjunction with the mustache(5) manual).  We can start fleshing out
> the API more fully in the docstrings as we work on other stuff.  And
> as above, we should of course raise for discussion any potential
> breaking changes that we're not sure about.

Excellent.

>> As a side note, between work/family/kids, I may not always get to
>> reply as promptly as I'd like.
>
> Good to know.  No rush.. :)
>
> --Chris
>

Tim ^,^

Re: [pystache] initial planning

From:
Chris Jerdonek
Date:
2011-11-29 @ 17:08
On Tue, Nov 29, 2011 at 2:33 AM, Tim Kersten <tim@io41.com> wrote:
> On Tue, Nov 29, 2011 at 04:46, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
>> On Mon, Nov 28, 2011 at 7:53 PM, Tim Kersten <tim@io41.com>
>> I was
>> thinking that maybe we could take a hybrid approach where we evaluate
>> each request in chronological order -- taking into account things like
>> ease or difficulty, and whether acting on it later could become
>> significantly easier because of anticipated refactorings, etc.  And
>> then act on the request based on the evaluation.  In any case, there
>> would be at least some discussion at each point along the way.
>
> That make sense, I like it. I would say let's start reviewing these as
> you suggested, and if you and I and anyone else who'd like to weigh in
> on any particular pull request are in agreement, we accept it.

Sounds good.  Are you okay with evaluating each issue here?  Then we
can post the discussion outcome on the issue itself.  The reason I
suggest this is that the discussions may very well branch out into
discussing future refactorings and the direction of things, etc.  It
will be awkward to go back and forth between the issues forum and
here.  If onlookers disagree with the posted outcome, they can always
respond on the issues forum and we can go from there.

What is the first request?  You can start an e-mail with a new subject line.

>> We probably also shouldn't rule out the possibility that other work
>> could be going on in parallel by others, e.g. adding a test harness
>> against the spec.
>
> Not for right now: I'm interested in adding a test harness to the
> development branch as soon as possible so I'll take a look at work
> done on this and merge as appropriate. On a related note, I'd like to
> see pystache getting tested for these against 2.6, 2.7, 3.2 on the
> various cpython supported platforms, and pypy too, though I think
> we're a bit away from that becoming practical yet.

Agreed.  Though can you clarify what you meant by "not for right now"?
 Did you mean we shouldn't do what I suggested right now, or that what
you're thinking about doing (adding the test harness, etc) isn't for
right now?

>> My only somewhat strong feeling is that we don't put a barrier in
>> place before we can start acting on requests, e.g. requiring that we
>> have a test harness against the spec in place and that passes before
>> we can start or that our public API be fully documented, etc.
>
> Good point. Besides, the current version is < 1.0,

Though how do we know Semantic Versioning is currently in place (j/k). :)

> so to quote the
> Semantic Version Specification:
>
>> Major version zero (0.y.z) is for initial development. Anything may
>> change at any time. The public API should not be considered stable.
>
> With this in mind, I'd like to propose we officially adopt
> http://semver.org/ for pystache. Thoughts?

Sounds good!

--Chris

Re: [pystache] initial planning

From:
Tim Kersten
Date:
2011-11-30 @ 08:50
On Tue, Nov 29, 2011 at 17:08, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
> On Tue, Nov 29, 2011 at 2:33 AM, Tim Kersten <tim@io41.com> wrote:
>> On Tue, Nov 29, 2011 at 04:46, Chris Jerdonek <chris.jerdonek@gmail.com> wrote:
>>> On Mon, Nov 28, 2011 at 7:53 PM, Tim Kersten <tim@io41.com>
>>> I was
>>> thinking that maybe we could take a hybrid approach where we evaluate
>>> each request in chronological order -- taking into account things like
>>> ease or difficulty, and whether acting on it later could become
>>> significantly easier because of anticipated refactorings, etc.  And
>>> then act on the request based on the evaluation.  In any case, there
>>> would be at least some discussion at each point along the way.
>>
>> That make sense, I like it. I would say let's start reviewing these as
>> you suggested, and if you and I and anyone else who'd like to weigh in
>> on any particular pull request are in agreement, we accept it.
>
> Sounds good.  Are you okay with evaluating each issue here?  Then we
> can post the discussion outcome on the issue itself.  The reason I
> suggest this is that the discussions may very well branch out into
> discussing future refactorings and the direction of things, etc.  It
> will be awkward to go back and forth between the issues forum and
> here.  If onlookers disagree with the posted outcome, they can always
> respond on the issues forum and we can go from there.

Perfect.

> What is the first request?  You can start an e-mail with a new subject line.
>
>>> We probably also shouldn't rule out the possibility that other work
>>> could be going on in parallel by others, e.g. adding a test harness
>>> against the spec.
>>
>> Not for right now: I'm interested in adding a test harness to the
>> development branch as soon as possible so I'll take a look at work
>> done on this and merge as appropriate. On a related note, I'd like to
>> see pystache getting tested for these against 2.6, 2.7, 3.2 on the
>> various cpython supported platforms, and pypy too, though I think
>> we're a bit away from that becoming practical yet.
>
> Agreed.  Though can you clarify what you meant by "not for right now"?
>  Did you mean we shouldn't do what I suggested right now, or that what
> you're thinking about doing (adding the test harness, etc) isn't for
> right now?

That was worded ambiguously, sorry. I agree with you, and I was
referring to my plans for pystache with "not for right now".

>
>>> My only somewhat strong feeling is that we don't put a barrier in
>>> place before we can start acting on requests, e.g. requiring that we
>>> have a test harness against the spec in place and that passes before
>>> we can start or that our public API be fully documented, etc.
>>
>> Good point. Besides, the current version is < 1.0,
>
> Though how do we know Semantic Versioning is currently in place (j/k). :)
>
>> so to quote the
>> Semantic Version Specification:
>>
>>> Major version zero (0.y.z) is for initial development. Anything may
>>> change at any time. The public API should not be considered stable.
>>
>> With this in mind, I'd like to propose we officially adopt
>> http://semver.org/ for pystache. Thoughts?
>
> Sounds good!
>
> --Chris
>