You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@allura.apache.org by Cory Johns <jo...@gmail.com> on 2014/03/05 21:18:07 UTC
Version tracking in repo
I'd like to propose, and request feedback for, an idea for tracking the
version number for Allura.
I think we've pretty well settled on using semantic versioning (see:
semver.org), which requires the MAJOR version number to be increased
whenever an "incompatible API change." As it might not always be obvious
from the ticket or commit log whether an incompatible change has been made,
I propose that we start tracking at least part of the version number in the
repository itself, e.g., in a VERSION file. This way, it will be obvious
when the MAJOR version number must change, as it can be updated along with
the code change that necessitates it.
Since we likely don't want to increase the version number with each commit
(or do we?), we could instead track the "API version" in the repository,
and only update the MINOR and PATCH versions upon release, external to the
code itself.
Alternatively, we could track both the MAJOR and MINOR version numbers in
the repository, which would require us to update the MINOR version number
for (and resolve conflicts between) each ticket that adds a new, backwards
compatible feature. This would take all of the guesswork / judgement out
of determining the release version. However, I think that Allura is still
proceeding with a sufficient amount of feature development that doing it
this way would cause more conflict on the version number than would be
worth the benefit.
Anyway, what are others' thoughts?
Re: Version tracking in repo
Posted by Dave Brondsema <da...@brondsema.net>.
+1
On 3/7/14 12:07 PM, Cory Johns wrote:
> Oh, good, so we already have a version in place, we just need to
> incorporate it better in the release process. That makes things much
> easier.
>
> With regards to "API version," yes, I meant that as synonymous with the
> MAJOR part of the MAJOR.MINOR.PATCH version scheme, as semver.org describes
> the MAJOR version as changing whenever a backwards-incompatible API change
> occurs (with MINOR changing when new backwards-compatible features are
> added, and PATCH changing with any backwards-compatible bug fixes). But I
> could see calling MAJOR.MINOR the "API version" since even not all of our
> new "features" necessarily affect the API (i.e., warranting a modification
> to http://allura.sourceforge.net/docs/#api-documentation). As long as our
> version number has a consistent semantic meaning, I think it's really up to
> us to establish a convention.
>
> Our existing version.py file has a two-part version number, so I guess we
> should bring that up to date, and integrate it with the release script.
> The release script can just compare the most recent asf_release_* tag with
> the version.py file and either increment or reset the patch version number,
> as appropriate. Then, it's just up to us to keep the version.py file up to
> date in the commits that make changes.
>
>
> On Fri, Mar 7, 2014 at 9:49 AM, Dave Brondsema <da...@brondsema.net> wrote:
>
>> On 3/5/14 3:18 PM, Cory Johns wrote:
>>> I'd like to propose, and request feedback for, an idea for tracking the
>>> version number for Allura.
>>>
>>> I think we've pretty well settled on using semantic versioning (see:
>>> semver.org), which requires the MAJOR version number to be increased
>>> whenever an "incompatible API change." As it might not always be obvious
>>> from the ticket or commit log whether an incompatible change has been
>> made,
>>> I propose that we start tracking at least part of the version number in
>> the
>>> repository itself, e.g., in a VERSION file. This way, it will be obvious
>>> when the MAJOR version number must change, as it can be updated along
>> with
>>> the code change that necessitates it.
>>
>> I was about to write about storing it in a var in Allura/allura/version.py
>> and
>> bring it into setup.py too (so packaging and other code can access it),
>> but it
>> looks like we already do that! But we haven't kept the version number in
>> that
>> file accurate. We should do so and put a reminder in our release script
>> steps.
>>
>>>
>>> Since we likely don't want to increase the version number with each
>> commit
>>> (or do we?), we could instead track the "API version" in the repository,
>>> and only update the MINOR and PATCH versions upon release, external to
>> the
>>> code itself.
>>
>> By "API version" do you mean the MAJOR part of the version number? Or
>> something
>> else?
>>
>>>
>>> Alternatively, we could track both the MAJOR and MINOR version numbers in
>>> the repository, which would require us to update the MINOR version number
>>> for (and resolve conflicts between) each ticket that adds a new,
>> backwards
>>> compatible feature. This would take all of the guesswork / judgement out
>>> of determining the release version. However, I think that Allura is
>> still
>>> proceeding with a sufficient amount of feature development that doing it
>>> this way would cause more conflict on the version number than would be
>>> worth the benefit.
>>
>> Yeah, I agree. I think updating the version proactively for api-breaking
>> changes makes sense, so that we don't forget about those changes. But
>> most of
>> the time version can be determined at release time, when reviewing the
>> whole set
>> of changes.
>>
>>>
>>> Anyway, what are others' thoughts?
>>>
>>
>>
>>
>> --
>> Dave Brondsema : dave@brondsema.net
>> http://www.brondsema.net : personal
>> http://www.splike.com : programming
>> <><
>>
>
--
Dave Brondsema : dave@brondsema.net
http://www.brondsema.net : personal
http://www.splike.com : programming
<><
Re: Version tracking in repo
Posted by Cory Johns <jo...@gmail.com>.
Oh, good, so we already have a version in place, we just need to
incorporate it better in the release process. That makes things much
easier.
With regards to "API version," yes, I meant that as synonymous with the
MAJOR part of the MAJOR.MINOR.PATCH version scheme, as semver.org describes
the MAJOR version as changing whenever a backwards-incompatible API change
occurs (with MINOR changing when new backwards-compatible features are
added, and PATCH changing with any backwards-compatible bug fixes). But I
could see calling MAJOR.MINOR the "API version" since even not all of our
new "features" necessarily affect the API (i.e., warranting a modification
to http://allura.sourceforge.net/docs/#api-documentation). As long as our
version number has a consistent semantic meaning, I think it's really up to
us to establish a convention.
Our existing version.py file has a two-part version number, so I guess we
should bring that up to date, and integrate it with the release script.
The release script can just compare the most recent asf_release_* tag with
the version.py file and either increment or reset the patch version number,
as appropriate. Then, it's just up to us to keep the version.py file up to
date in the commits that make changes.
On Fri, Mar 7, 2014 at 9:49 AM, Dave Brondsema <da...@brondsema.net> wrote:
> On 3/5/14 3:18 PM, Cory Johns wrote:
> > I'd like to propose, and request feedback for, an idea for tracking the
> > version number for Allura.
> >
> > I think we've pretty well settled on using semantic versioning (see:
> > semver.org), which requires the MAJOR version number to be increased
> > whenever an "incompatible API change." As it might not always be obvious
> > from the ticket or commit log whether an incompatible change has been
> made,
> > I propose that we start tracking at least part of the version number in
> the
> > repository itself, e.g., in a VERSION file. This way, it will be obvious
> > when the MAJOR version number must change, as it can be updated along
> with
> > the code change that necessitates it.
>
> I was about to write about storing it in a var in Allura/allura/version.py
> and
> bring it into setup.py too (so packaging and other code can access it),
> but it
> looks like we already do that! But we haven't kept the version number in
> that
> file accurate. We should do so and put a reminder in our release script
> steps.
>
> >
> > Since we likely don't want to increase the version number with each
> commit
> > (or do we?), we could instead track the "API version" in the repository,
> > and only update the MINOR and PATCH versions upon release, external to
> the
> > code itself.
>
> By "API version" do you mean the MAJOR part of the version number? Or
> something
> else?
>
> >
> > Alternatively, we could track both the MAJOR and MINOR version numbers in
> > the repository, which would require us to update the MINOR version number
> > for (and resolve conflicts between) each ticket that adds a new,
> backwards
> > compatible feature. This would take all of the guesswork / judgement out
> > of determining the release version. However, I think that Allura is
> still
> > proceeding with a sufficient amount of feature development that doing it
> > this way would cause more conflict on the version number than would be
> > worth the benefit.
>
> Yeah, I agree. I think updating the version proactively for api-breaking
> changes makes sense, so that we don't forget about those changes. But
> most of
> the time version can be determined at release time, when reviewing the
> whole set
> of changes.
>
> >
> > Anyway, what are others' thoughts?
> >
>
>
>
> --
> Dave Brondsema : dave@brondsema.net
> http://www.brondsema.net : personal
> http://www.splike.com : programming
> <><
>
Re: Version tracking in repo
Posted by Dave Brondsema <da...@brondsema.net>.
On 3/5/14 3:18 PM, Cory Johns wrote:
> I'd like to propose, and request feedback for, an idea for tracking the
> version number for Allura.
>
> I think we've pretty well settled on using semantic versioning (see:
> semver.org), which requires the MAJOR version number to be increased
> whenever an "incompatible API change." As it might not always be obvious
> from the ticket or commit log whether an incompatible change has been made,
> I propose that we start tracking at least part of the version number in the
> repository itself, e.g., in a VERSION file. This way, it will be obvious
> when the MAJOR version number must change, as it can be updated along with
> the code change that necessitates it.
I was about to write about storing it in a var in Allura/allura/version.py and
bring it into setup.py too (so packaging and other code can access it), but it
looks like we already do that! But we haven't kept the version number in that
file accurate. We should do so and put a reminder in our release script steps.
>
> Since we likely don't want to increase the version number with each commit
> (or do we?), we could instead track the "API version" in the repository,
> and only update the MINOR and PATCH versions upon release, external to the
> code itself.
By "API version" do you mean the MAJOR part of the version number? Or something
else?
>
> Alternatively, we could track both the MAJOR and MINOR version numbers in
> the repository, which would require us to update the MINOR version number
> for (and resolve conflicts between) each ticket that adds a new, backwards
> compatible feature. This would take all of the guesswork / judgement out
> of determining the release version. However, I think that Allura is still
> proceeding with a sufficient amount of feature development that doing it
> this way would cause more conflict on the version number than would be
> worth the benefit.
Yeah, I agree. I think updating the version proactively for api-breaking
changes makes sense, so that we don't forget about those changes. But most of
the time version can be determined at release time, when reviewing the whole set
of changes.
>
> Anyway, what are others' thoughts?
>
--
Dave Brondsema : dave@brondsema.net
http://www.brondsema.net : personal
http://www.splike.com : programming
<><