development process

I’ve been prompted to think about CSL development process again, but two things:

  1. Rintze issued a pull request and I accepted it too quickly. But
    what should be the proper process? What’s the appropriate time-frame?
    How do we deal with dissent? Also, I think in general Rintze has been
    a little frustrated with the not-entirely fluid process.

  2. some tension in the Sakai world around OAE development process, in
    which Ian Boston advocated for the Apache model

So I looked at the Apache model:

https://blogs.apache.org/comdev/entry/how_apache_projects_use_consensus

… and want to ask what we should do?

I floated one idea (which is basically to use github pull requests +
Apache model for spec or schema change proposals) here:

https://github.com/citation-style-language/documentation/pull/18#issuecomment-1493667

So in other words, pull requests require concrete proposals (though we
have the problem they may be split across two projects,
unfortunately), and the Apache process (essentially, any member has a
veto right, and we have an explicit focus on consensus) makes sure
we’re on the same page.

Bruce

I’ve been prompted to think about CSL development process again, but two
things:

  1. Rintze issued a pull request and I accepted it too quickly. But
    what should be the proper process? What’s the appropriate time-frame?
    How do we deal with dissent? Also, I think in general Rintze has been
    a little frustrated with the not-entirely fluid process.

I’m not frustrated. I think pull requests can be handy for discussing schema
and spec changes. It even allows for collaborative editing (all that is
needed is for me to give commit rights to my fork; any additional commits in
the feature branches will appear in my pull requests). It’s just rather
unhandy that it’s currently impossible to link pull requests to existing
issues. I think things should work fine if: a) I clearly link pull requests
to any existing relevant issues, and b) the other main CSL contributors
indicate approval or disapproval of the changes in the pull request. It
would be great if pull requests can be reviewed within about two weeks, to
keep some pace of development.

As for dissent: it has proven to be difficult to get timely feedback from
all parties involved in CSL. So again, to keep things moving I think I
should take the liberty of being slightly aggressive in making commits. I’m
always open to feedback, and there’s plenty time before releases to reflect
on things. I’m planning to maintain a changelog with (proposed) CSL 1.0.1
changes so everybody can more easily keep track of things. I’m fine with
vetoing power for all, assuming they can support their case.

  1. some tension in the Sakai world around OAE development process, in

which Ian Boston advocated for the Apache model

So I looked at the Apache model:

https://blogs.apache.org/comdev/entry/how_apache_projects_use_consensus

… and want to ask what we should do?

I floated one idea (which is basically to use github pull requests +
Apache model for spec or schema change proposals) here:

<
https://github.com/citation-style-language/documentation/pull/18#issuecomment-1493667

So in other words, pull requests require concrete proposals (though we
have the problem they may be split across two projects,
unfortunately), and the Apache process (essentially, any member has a
veto right, and we have an explicit focus on consensus) makes sure
we’re on the same page.

Yes, I’m wondering if there would be an easier way to discuss CSL changes.
In the old days, we mostly relied on the xbiblio list. Now, we have the
xbiblio list, the Bitbucket citeproc-test, and 5 Github CSL repos, all with
their respective issue trackers. That’s not much of a problem for me, but I
can imagine it looks rather unorganized for outsiders.

Rintze

I’ve been prompted to think about CSL development process again, but two things:

  1. Rintze issued a pull request and I accepted it too quickly. But
    what should be the proper process? What’s the appropriate time-frame?
    How do we deal with dissent? Also, I think in general Rintze has been
    a little frustrated with the not-entirely fluid process.

I’m not frustrated. I think pull requests can be handy for discussing schema and spec changes. It even allows for collaborative editing (all that is needed is for me to give commit rights to my fork; any additional commits in the feature branches will appear in my pull requests). It’s just rather unhandy that it’s currently impossible to link pull requests to existing issues. I think things should work fine if: a) I clearly link pull requests to any existing relevant issues, and b) the other main CSL contributors indicate approval or disapproval of the changes in the pull request. It would be great if pull requests can be reviewed within about two weeks, to keep some pace of development.

Quick search says while one can’t currently attach a pull request to
an existing issue in the UI, one can do it via the API:

http://goldendict.org/forum/viewtopic.php?f=6&t=1153

As for dissent: it has proven to be difficult to get timely feedback from all parties involved in CSL. So again, to keep things moving I think I should take the liberty of being slightly aggressive in making commits. I’m always open to feedback, and there’s plenty time before releases to reflect on things. I’m planning to maintain a changelog with (proposed) CSL 1.0.1 changes so everybody can more easily keep track of things. I’m fine with vetoing power for all, assuming they can support their case.

What would be the precise workflow, then? Would these changes be
maintained on a branch? How would you roll back a specific changes two
months after the fact?

Do we want to formalize some standard time-frame for feedback?

  1. some tension in the Sakai world around OAE development process, in
    which Ian Boston advocated for the Apache model

So I looked at the Apache model:

https://blogs.apache.org/comdev/entry/how_apache_projects_use_consensus

… and want to ask what we should do?

I floated one idea (which is basically to use github pull requests +
Apache model for spec or schema change proposals) here:

https://github.com/citation-style-language/documentation/pull/18#issuecomment-1493667

So in other words, pull requests require concrete proposals (though we
have the problem they may be split across two projects,
unfortunately), and the Apache process (essentially, any member has a
veto right, and we have an explicit focus on consensus) makes sure
we’re on the same page.

Yes, I’m wondering if there would be an easier way to discuss CSL changes. In the old days, we mostly relied on the xbiblio list. Now, we have the xbiblio list, the Bitbucket citeproc-test, and 5 Github CSL repos, all with their respective issue trackers. That’s not much of a problem for me, but I can imagine it looks rather unorganized for outsiders.

To me, the biggest problem is (in hindsight) is the split between
schema, spec, tests. But I don’t know what to do about it now.

What I think we basically need is a process that is a) a little more
transparent and clear, and b) more easily self-sustaining.

Bruce

See also:

http://stackoverflow.com/questions/4528869/how-do-you-attach-a-new-pull-request-to-an-existing-issue-on-github

Bruce

I’d like to resurrect this thread, which failed to get any feedback
from the broader development community.

It’s prompted by the fact that I have just felt compelled formally
objected to a patch that Rintze made.

https://github.com/citation-style-language/schema/issues/50

In my view, this should require the patch be rolled back, and that
anyone on this list has the authority to similarly object to changes.

If we’re not going to adopt such a process, then I think we’re heading
for trouble.

Bruce

And to give you an idea of details, here’s a general description of
the apache voting process:

http://www.apache.org/foundation/voting.html

… and an example closer to CSL, of a recent specification:

http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/4759a30ed73c5af8#

So in this case, they open up a formal voting process for a specific
release (OpenSocial 2.0) against a specific revision with a list of
patches, open for a defined time-period. People signed up with voting
rights vote.

Note also there are different kinds of votes. The standard one (for
more important changes I guess) require at least three +1 votes. The
lazy-consensus vote has a lower-bar.

We essentially need to make the revision process for CSL as
easy-as-possible to manage (technically and socially), but also one
that leads to predictability for development.

If anyone has any particular ideas of how to best operationalize this
for CSL, I’d like to hear them.

I suggested to Rintze, for example, that one possibility after 1.01 is
to merge some of the repos so that patches can be more easily
identified and isolated. Perhaps a new feature, then, would have a
feature branch, and we could periodically collect a few to vote on,
maybe some with lazy voting, and others with a higher-bar?

Bruce