search

adlnet / xAPI-Spec

The xAPI Specification describes communication about learner activity and experiences between technologies.
https://adlnet.gov/projects/xapi/
898 stars 404 forks source link

Modifying the Master Branch vs. Dev #1060

Open andyjohnson opened 6 years ago

andyjohnson commented 6 years ago

After talking about merging a recent PR around fixing a mistake in an example in the specification, @garemoko raised a good point - should we allow master to be modified at all? Could it be a slippery slope to causing an issue around conformance?

I think we've all already agreed that the README is an exception to this rule, with it having up-to-date information about meetings, etc., but what else?

I'd say that the line should go no further than the following: Changes that are purely technical/typo as well as any changes to examples. I'm up for moving that line to be even stricter with what we allow, but consider the following:

1) The GitHub whitespace processing changed causing us to re-format master - I think this was acceptable 2) I see no problem fixing things that are clearly typos in capitalization/spelling unless that would happen to change actual meaning of the spec. Wordsmithing is NOT permitted. 3) Where there is the greatest chance for discussion is around examples. I feel that leaving bad examples up in the version of the spec to which people most often go to will cause more harm than good. I could also see the argument of claiming conformance because the spec example "said it was okay by example", and then it has changed.

I'm curious to think how everyone feels on this topic. Thanks!

garemoko commented 6 years ago

I'm responding to @cr8onski's message in this thread.

@cr8onski said...

@garemoko are you talking about waiting for patch 1.0.4? If so, I think that is too long to show off a incorrect example.

If it is just a week or two to gather up all the most recent typos, etc that have been caught, I'd be for that.

Yes, that's what I mean. I also wouldn't be against more rapid releases of patch versions (maybe every 3 or 6 months). Bear in mind that the error has existed since December 2014 before anybody noticed and people can always check the development branch to see fixed errors.

I have two reasons for wanting to keep this kind of change to actual releases:

  1. Actual releases get much closer review, helping to avoid the case where we "correct" an example but actually introduce a new error. The same could potentially apply to apparent typos.
  2. As the development branch moves away from master, more changes to master could lead to conflicts. Sometimes difficult to review errors get introduced during conflict merges.