Code reviews and public API changes

Gustavo Niemeyer gustavo.niemeyer at canonical.com
Thu Nov 10 16:18:20 UTC 2011


Dear juju hackers,

We've already debated this over UDS, but it'd be nice to have it
firmly agreed and in a more pragmatic prose, so I'm sending this as a
strawman proposal to see if we can put something more concrete in
place.

The topic is that we need to learn to separate code changes that are
implementation details from public API changes. We need have public
API changes being debated here in the mailing list, before they are
made into a code review, landed, and released. Code reviews are meant
to cover how something was done and implemented, but not high-level
design aspects.

Here is a list of things we should cover in the mailing list, to make
the proposal more tangible:

- Introduction of new commands and sub-commands
- Changes to the public API of existing commands (output, flags, etc)
- Behavioral changes (hook execution semantics, environment variables, etc)
- ZooKeeper content and semantics [1]

To get used to this process, to enable the community to voice in, and
also to ensure we have historic records for debates around these, we
should _always_ be able to match such a change to a thread in the
mailing list. IRC doesn't count, voice meetings doesn't count, content
in a bug doesn't count unless it's referred to from a mailing list
thread.

To contrast, these are issues that don't have to have their design
debated upfront:

- Implementation of agreed specifications
- Code reorganization
- All kinds of fixes (docs, bugs, tests, etc)

Note that even though the smaller list is significantly smaller than
the former one, the vast majority of our time is spent on the bottom
one, not on the top one, so I don't expect this will be a significant
burden.

Can we agree to this?


[1] This one is slightly special in that it's almost an implementation
detail, but since we'll be trying to match the behavior in a port, it
becomes a public API too.

-- 
Gustavo Niemeyer
http://niemeyer.net
http://niemeyer.net/plus
http://niemeyer.net/twitter
http://niemeyer.net/blog

-- I'm not absolutely sure of anything.



More information about the Juju mailing list