Forum OpenACS Improvement Proposals (TIPs): TIP # 23 (Clarify/Resubmit): Core code changes and bug fixes require approved TIP.

I should clarify that this was meant to apply to API changes, not every line of every file in a core package.

Is there currently any other place someone can follow changes? I had thought a separate forum where api changes could be at least logged might be helpful.

My opinion is that a lot of thought goes into changing an api, but this thought remains in the head of the person making the changes. It might be obvious in a lot of cases why the change is being made. Other times not.

I think that at a minimum, anything that breaks backwards compatibility should require a TIP.

Joel - do you mean changes to "actual" or "documented" functionality?

I'm assuming (based on the poster and timing) that this TIP is a reaction to the ad_page_contract stuff, so within that context - if the rule is that changes to the documented behaviour of core APIs require a TIP then Jun's changes wouldn't have required one (since the behaviour when vars are set before ad_page_contract is called isn't specified in the documentation).

Conversely, if the rule is that any changes to behaviour of core APIs for a given set of inputs (changes to existing functionality rather than API additions) require a TIP, then people are in effect being encouraged to add flags to handle the quirks of their own requirements, which in my opinion is likely to lead to a *more* fragmented and harder to understand API.

I don't know what the solution here is, but I don't think it lies in setting formal rules that won't in practice be followed.

DO NOT EVER BREAK EXISTING CODE

I know that it's more difficult to work this way because you can't just change the code when you want. But I've seen too many packages move from working to obsolete because they "don't have adequate maintenance". The point is, they should require *no* maintenance once they are accepted into the mainstream. If a great, new, slick API is appropriate and it is *not* compatible with existing code, it should go into a new namespace and existing core (or other package) code should be refactored to interface with the new API.

• Nobody's code breaks
• Packages only become obsolete when a newer, bigger, better package provides better service than the existing package
• Developers don't have to refactor tested and QA'd production code every time a new OACS release comes out
• Users can keep up with *every* new release if they want to
• Contributions by developers to the community do not become a maintenance nightmare

What I'm suggesting is:

- API change that breaks the core: TIP
- Every other API change (including packages): Post in an API change forum.

If people are unhappy with a change, they can start the discussion around the announcement.

- You remove a parameter
- You change the way the parameter is beeing used in a not obvious way (e.g. if you suddenly decide to user first_names as the container for the birthdate).
- You change the return values (number / order)

And this is why I said, if in doubt, just announce it. The commiter might not be aware of it, or too overworked to notice (we are humans. Humans are prone to make error). Therefore I absolutly second Dirks request for a CVS diff mailinglist. It has helped us internally tremendously so far and prevents serious mistakes to get into the code (and teaches a little bit of coding style and commit comments).

Nobody wants to do it, but once in a while it turns out that it is impossible. For the upcoming 5.0 release I18N doesn't break the past, the templating system change does. There simply was no other way to fix this behaviour.

We need to balance stability with being able to move forward - let's see how OCT governance works out.

Well there were lots of good ideas and different perspectives which I hadn't considered. For one, I didn't realize that the core API was changing so rapidly. Most of the packages I have written have worked unchanged for the last several years, maybe with the exception of the context bar.

So first off, I think my idea of what the core APIs include isn't as broad as what is actually in the core.

Second, my proposal wasn't to stop _any_ change or coding from taking place. The main ideas, maybe poorly communicated, were:

• that there should be a central place where the reasons for the changes are recorded. Maybe explaining the changes so that folks know what to expect, without looking at a cvs log and piecing togeather that with the original file.
• that the OCT take active oversight of these changes. Maybe that means something as simple as reading about the changes. Since cvs is always there to revert changes, my main concern is that a change, which is not good, goes in to support a package, unintentionally breaking other packages. Once another package needs this change, it is hard to use cvs to fix the matter.
• Someone reviews the code for core changes. I think the rules and responsibilities TIP had some ideas about that. The package maintainer needed to review patches before they were used on the core.
• The TIP process is finite. Discussions on what changes should take place that happen on the regular forums are not. If someone gets tired of talking about what they are going to change, and they have commit rights, they can just stop and make the change anyway. A TIP makes the decision process understandable to everyone, and it gets multiple views into the discussion. Regular forum discussions usually only involve a few voices, and maybe not the most knowledgeable ones on the subject. I know that after reading this TIP, my opinions have changed and my understanding of the issues have expanded. My opinion: this is the point of the TIP process. One or two, or even three dissenting voices isn't going to stop a change.

Third: revoking commit rights should always be possible. It should be as easy as getting them in the process. But this would probably be rarely applied. I didn't see it as harsh because I didn't imagine that it would happen very often. However Jeff's points are good. Maybe this is too heavy a stick and it could be used as a punishment. Removing commit rights is something that can be dealt with completely separately from the main issue of documenting core API changes.