"which version/branch should I use?"

We've seen this issue before:

  - If you are in Pharo1.4, which Metacello version of project X
    should you use

While not perfect, the #stable symbolic version has given us a mechanism for answering that question and when all of the #stable versions are defined and aligned it appears to work well enough.

With git we have the same problem:

  - If you are in Pharo1.4, which git SHA, tag, branch (commit-ish) of project X
    should you use

We cannot store this version meta information in the git repository along with the project, because the answer to the question changes over time and we can't go back to an earlier commit of the project and change that information...

This implies that we need to maintain a separately versioned mapping between platform versions and the git commit-ish.

At this point in time I don't have any good answers for the problem ...

If you go to the FileTree Tags page[1], you'll notice that as a human being you can make an informed guess as to which of the tags to use and the same applies to the branches as well...

As a developer of the project I can also maintain a map (separately versioned from the project artifacts) between platform versions and the appropriate git commit-ish.

Do we have a central repository of maps for common (all?) projects ala ruby gems?

Do we have a convention that each developer create a github project that provides the version mapping?

Other ideas?

I'll probably be focusing on this issue in the next few days so any ideas or brainstorming would be greatly appreciated ...

Dale


[1] https://github.com/dalehenrich/filetree/tags 

On 11 April 2012 18:39, Dale Henrichs <[hidden email]> wrote:
I'm not sure I understand the problem. I would expect in some random
project to see one master branch containing the latest code. Off that
I'd expect to see some version branch, say REL-1.2. Certain commits
would be tagged 1.2, 1.2.1, and so on on that branch, indicating
commits from which versions have been released. Somewhere in my
documentation I'd say "if you're running Pharo run Foo 1.2. You can
get it by <insert instructions>" which might say "git init; git clone;
git checkout 1.2.2".

So perhaps the problem you describe is how to answer "Crumbs, I'm
running Pharo. Which version of Foo do I use? Ah, I'll use #stable!"
and then that leads to "Oh. To what version does #stable point?"

But that in turn is an easily addressable question. In or before the
commit tagged 1.2.1, some commit sets/updates the mapping. In other
words, for the commit tagged 1.2.1 I'd expect to see something like

stable: spec
        <symbolicVersion: #'stable'>

--- spec for: #'common' version: '1.2.1'
+++ spec for: #'common' version: '1.2.2'

in whatever file contains ConfigurationOfFoo >> #stable:.

Unless of course I'm missing the problem!

> If you go to the FileTree Tags page[1], you'll notice that as a human being you can make an informed guess as to which of the tags to use and the same applies to the branches as well...
>
> As a developer of the project I can also maintain a map (separately versioned from the project artifacts) between platform versions and the appropriate git commit-ish.
>
> Do we have a central repository of maps for common (all?) projects ala ruby gems?

I don't think we do, but we should. That could be something as simple
as a chunk of JSON in a github project. Well, it should have a simple
API that _lets_ us use a chunk of JSON, with the option of replacing
that with a proper solution :)

Oh, wait. I suspect that squeak-dev would say "Yes we do. It's called
SqueakMap, and we should use that." Maybe we can put a bit of effort
into SqueakMap and get extra bang for our buck?

----- Original Message -----
| From: "Frank Shearar" <[hidden email]>
| To: [hidden email]
| Sent: Thursday, April 12, 2012 2:18:57 AM
| Subject: Re: [Metacello] "which version/branch should I use?"
|
| On 11 April 2012 18:39, Dale Henrichs <[hidden email]> wrote:
| > We've seen this issue before:
| >
| >  - If you are in Pharo1.4, which Metacello version of project X
| >    should you use
| >
| > While not perfect, the #stable symbolic version has given us a
| > mechanism for answering that question and when all of the #stable
| > versions are defined and aligned it appears to work well enough.
| >
| > With git we have the same problem:
| >
| >  - If you are in Pharo1.4, which git SHA, tag, branch (commit-ish)
| >  of project X
| >    should you use
| >
| > We cannot store this version meta information in the git repository
| > along with the project, because the answer to the question changes
| > over time and we can't go back to an earlier commit of the project
| > and change that information...
| >
| > This implies that we need to maintain a separately versioned
| > mapping between platform versions and the git commit-ish.
| >
| > At this point in time I don't have any good answers for the problem
| > ...
|
| I'm not sure I understand the problem. I would expect in some random
| project to see one master branch containing the latest code. Off that
| I'd expect to see some version branch, say REL-1.2. Certain commits
| would be tagged 1.2, 1.2.1, and so on on that branch, indicating
| commits from which versions have been released. Somewhere in my
| documentation I'd say "if you're running Pharo run Foo 1.2. You can
| get it by <insert instructions>" which might say "git init; git
| clone;
| git checkout 1.2.2".
|
| So perhaps the problem you describe is how to answer "Crumbs, I'm
| running Pharo. Which version of Foo do I use? Ah, I'll use #stable!"
| and then that leads to "Oh. To what version does #stable point?"

This is exactly the area of concern, especially when it gets into the area of specifying a project dependency for your project .. the point of the symbolic versions is that the #stable version can and will change over time and new platform versions can be added without requiring me to change my configuration everytime a new version of Seaside is released.

|
| But that in turn is an easily addressable question. In or before the
| commit tagged 1.2.1, some commit sets/updates the mapping. In other
| words, for the commit tagged 1.2.1 I'd expect to see something like
|
| stable: spec
| <symbolicVersion: #'stable'>
|
| --- spec for: #'common' version: '1.2.1'
| +++ spec for: #'common' version: '1.2.2'

The difficulty is that the decision must be made "in or before" the commit. I will grant that the decision can often be made "in or before" the commit, but in some cases, the decision is made post-commit and that is not quite as easy ... and mistakes are even harder to undo ....

One of things that has occurred to me is that the file with the stable version declaration could be maintained at the head of the master branch (or perhaps the the head of the config branch) ... with github we could do a query and pull down that file, but if I am looking at a git repository on disk, it is not as easy to checkout the config branch and grab the file ... but if I am looking at a disk image on the local machine, how do I access the "other branch" ... it may just be a disk copy of the repository that came from SVN ...

Instead of thinking of the config branch as an attrribute of the repository, we could look at the config branch as an independent repository embedded in the repository (i.e., conceptually you would delete all files from this branch and only maintain config information here) and the config branch would be downloaded independently to a separate disk location on the local machine that is related to the filetree repository itself...

Perhaps the config branch is the right answer?

|
| in whatever file contains ConfigurationOfFoo >> #stable:.
|
| Unless of course I'm missing the problem!
|
| > If you go to the FileTree Tags page[1], you'll notice that as a
| > human being you can make an informed guess as to which of the tags
| > to use and the same applies to the branches as well...
| >
| > As a developer of the project I can also maintain a map (separately
| > versioned from the project artifacts) between platform versions
| > and the appropriate git commit-ish.
| >
| > Do we have a central repository of maps for common (all?) projects
| > ala ruby gems?
|
| I don't think we do, but we should. That could be something as simple
| as a chunk of JSON in a github project. Well, it should have a simple
| API that _lets_ us use a chunk of JSON, with the option of replacing
| that with a proper solution :)

along these lines, keep in mind that Metacello scripting api is intended to manage the develop environment for these projects so it will be possible to have a chain of places to look for config information:

  - local disk
  - config branch for project
  - central repository

in some order ...

|
| Oh, wait. I suspect that squeak-dev would say "Yes we do. It's called
| SqueakMap, and we should use that." Maybe we can put a bit of effort
| into SqueakMap and get extra bang for our buck?

The MetacelloRepository or SqueakMap is necessary from the point of view of providing a central location to register and look for projects ... otherwise github can be a giant wasteland that must be exhaustively searched for projects of interest ...

|
| > Do we have a convention that each developer create a github project
| > that provides the version mapping?
| >
| > Other ideas?
| >
| > I'll probably be focusing on this issue in the next few days so any
| > ideas or brainstorming would be greatly appreciated ...
| >
| > Dale
| >
| >
| > [1] https://github.com/dalehenrich/filetree/tags
|

On 12 April 2012 18:18, Dale Henrichs <[hidden email]> wrote:
For the purposes of describing the dependencies of an artifact, surely
you _don't_want_ #stable? You don't have a stable build process if you
have a #stable dependency: today you build your software and it works,
and tomorrow you build it again only Dependent-Widget just rolled out
a new version with an unintentional breaking change and you sit
scratching your head wondering what YOU did to break your build!

But otherwise, for the purpose of starting development, #stable is
certainly useful, and also useful as a means of self-documenting:
"What's the latest stable release? Oh, whatever #stable points to."

Yes. That's _mainly_ what rubygems does. OK, it also provides a
well-known hosting service for gems, but hosting the artifacts itself
or driving the hosting out to other services isn't important to users
of the software.

frank

----- Original Message -----
| From: "Frank Shearar" <[hidden email]>
| To: [hidden email]
| Sent: Thursday, April 12, 2012 12:10:28 PM
| Subject: Re: [Metacello] "which version/branch should I use?"
|
| On 12 April 2012 18:18, Dale Henrichs <[hidden email]> wrote:
| >
| >
| > ----- Original Message -----
| > | From: "Frank Shearar" <[hidden email]>
| > | To: [hidden email]
| > | Sent: Thursday, April 12, 2012 2:18:57 AM
| > | Subject: Re: [Metacello] "which version/branch should I use?"
| > |
| > | On 11 April 2012 18:39, Dale Henrichs <[hidden email]>
| > | wrote:
| > | > We've seen this issue before:
| > | >
| > | >  - If you are in Pharo1.4, which Metacello version of project X
| > | >    should you use
| > | >
| > | > While not perfect, the #stable symbolic version has given us a
| > | > mechanism for answering that question and when all of the
| > | > #stable
| > | > versions are defined and aligned it appears to work well
| > | > enough.
| > | >
| > | > With git we have the same problem:
| > | >
| > | >  - If you are in Pharo1.4, which git SHA, tag, branch
| > | >  (commit-ish)
| > | >  of project X
| > | >    should you use
| > | >
| > | > We cannot store this version meta information in the git
| > | > repository
| > | > along with the project, because the answer to the question
| > | > changes
| > | > over time and we can't go back to an earlier commit of the
| > | > project
| > | > and change that information...
| > | >
| > | > This implies that we need to maintain a separately versioned
| > | > mapping between platform versions and the git commit-ish.
| > | >
| > | > At this point in time I don't have any good answers for the
| > | > problem
| > | > ...
| > |
| > | I'm not sure I understand the problem. I would expect in some
| > | random
| > | project to see one master branch containing the latest code. Off
| > | that
| > | I'd expect to see some version branch, say REL-1.2. Certain
| > | commits
| > | would be tagged 1.2, 1.2.1, and so on on that branch, indicating
| > | commits from which versions have been released. Somewhere in my
| > | documentation I'd say "if you're running Pharo run Foo 1.2. You
| > | can
| > | get it by <insert instructions>" which might say "git init; git
| > | clone;
| > | git checkout 1.2.2".
| > |
| > | So perhaps the problem you describe is how to answer "Crumbs, I'm
| > | running Pharo. Which version of Foo do I use? Ah, I'll use
| > | #stable!"
| > | and then that leads to "Oh. To what version does #stable point?"
| >
| > This is exactly the area of concern, especially when it gets into
| > the area of specifying a project dependency for your project ..
| > the point of the symbolic versions is that the #stable version can
| > and will change over time and new platform versions can be added
| > without requiring me to change my configuration everytime a new
| > version of Seaside is released.
|
| For the purposes of describing the dependencies of an artifact,
| surely
| you _don't_want_ #stable?

Yes, sometimes. When you have a "loose dependency" on another project, then #stable is exactly what you want.

OmniBrowser is the perfect example ... If I'm using OmniBrowser in my project, I probably don't care exactly which version of OmniBrowser I'm using, but I do care that you get the correct version of OmniBrowser loaded for your platform ... and depending upon the #stable version does exactly that ...

Sooo, we can't just expect a developer to go look up on some website and figure out which version of the project to use in this case ...

The #stable version will almost certainly refer to a tag, but it is difficult to think in terms of a naming convention for tags (if we had a naming convention that works .. this issue can be resolved) .. the #stable_pharo tag name works until pharo1.4 breaks something then you have two tags

  - stable_pharo
  - stable_pharo1.4

If I'm now in pharo1.5 which one of the tags do I use? if any? ...

So I think we have to have a specific declaration process that is separately accessible and I'm beginning to like the notion of the 'config branch' more and more as a way to address this puppy...


| You don't have a stable build process if
| you
| have a #stable dependency: today you build your software and it
| works,
| and tomorrow you build it again only Dependent-Widget just rolled out
| a new version with an unintentional breaking change and you sit
| scratching your head wondering what YOU did to break your build!

You are correct, but in this case, you have a "tight dependency" on the project and you are concerned that any little change in the implementation might severely impact your own application's performance and you will specify a specific version number (a tag or SHA for git-based projects) to lock it in ...

I have been mulling over how to hook into the git submodules for this particular case ... we can't rely 100% on submodules, but we should make it possible to use submodules or a specific version interchangeably.

Additionally, the Metacello Scripting API will support the notion of "pinning the version of a project" so that you can guarantee that in you development enviornment a specific version of specific projects will always be used ...See the discussion starting with "Loaded Projects[1]" and "Registered projects" in the Glossary of Terms for the Metacello Scripting API.

[1] https://github.com/dalehenrich/MetacelloScriptingApiSpec/wiki/Glossaryofterms#wiki-loadedprojects
|
| But otherwise, for the purpose of starting development, #stable is
| certainly useful, and also useful as a means of self-documenting:
| "What's the latest stable release? Oh, whatever #stable points to."

Agreed.

|
| > | But that in turn is an easily addressable question. In or before
| > | the
| > | commit tagged 1.2.1, some commit sets/updates the mapping. In
| > | other
| > | words, for the commit tagged 1.2.1 I'd expect to see something
| > | like
| > |
| > | stable: spec
| > |       <symbolicVersion: #'stable'>
| > |
| > | ---   spec for: #'common' version: '1.2.1'
| > | +++   spec for: #'common' version: '1.2.2'
| >
| > The difficulty is that the decision must be made "in or before" the
| > commit. I will grant that the decision can often be made "in or
| > before" the commit, but in some cases, the decision is made
| > post-commit and that is not quite as easy ... and mistakes are
| > even harder to undo ....
| >
| > One of things that has occurred to me is that the file with the
| > stable version declaration could be maintained at the head of the
| > master branch (or perhaps the the head of the config branch) ...
| > with github we could do a query and pull down that file, but if I
| > am looking at a git repository on disk, it is not as easy to
| > checkout the config branch and grab the file ... but if I am
| > looking at a disk image on the local machine, how do I access the
| > "other branch" ... it may just be a disk copy of the repository
| > that came from SVN ...
| >
| > Instead of thinking of the config branch as an attrribute of the
| > repository, we could look at the config branch as an independent
| > repository embedded in the repository (i.e., conceptually you
| > would delete all files from this branch and only maintain config
| > information here) and the config branch would be downloaded
| > independently to a separate disk location on the local machine
| > that is related to the filetree repository itself...
| >
| > Perhaps the config branch is the right answer?
| >
| > |
| > | in whatever file contains ConfigurationOfFoo >> #stable:.
| > |
| > | Unless of course I'm missing the problem!
| > |
| > | > If you go to the FileTree Tags page[1], you'll notice that as a
| > | > human being you can make an informed guess as to which of the
| > | > tags
| > | > to use and the same applies to the branches as well...
| > | >
| > | > As a developer of the project I can also maintain a map
| > | > (separately
| > | > versioned from the project artifacts) between platform versions
| > | > and the appropriate git commit-ish.
| > | >
| > | > Do we have a central repository of maps for common (all?)
| > | > projects
| > | > ala ruby gems?
| > |
| > | I don't think we do, but we should. That could be something as
| > | simple
| > | as a chunk of JSON in a github project. Well, it should have a
| > | simple
| > | API that _lets_ us use a chunk of JSON, with the option of
| > | replacing
| > | that with a proper solution :)
| >
| > along these lines, keep in mind that Metacello scripting api is
| > intended to manage the develop environment for these projects so
| > it will be possible to have a chain of places to look for config
| > information:
| >
| >  - local disk
| >  - config branch for project
| >  - central repository
| >
| > in some order ...
| >
| > |
| > | Oh, wait. I suspect that squeak-dev would say "Yes we do. It's
| > | called
| > | SqueakMap, and we should use that." Maybe we can put a bit of
| > | effort
| > | into SqueakMap and get extra bang for our buck?
| >
| > The MetacelloRepository or SqueakMap is necessary from the point of
| > view of providing a central location to register and look for
| > projects ... otherwise github can be a giant wasteland that must
| > be exhaustively searched for projects of interest ...
|
| Yes. That's _mainly_ what rubygems does. OK, it also provides a
| well-known hosting service for gems, but hosting the artifacts itself
| or driving the hosting out to other services isn't important to users
| of the software.

I think that centralized servers providing version mapping information is a good thing, but I would like to preserve the current semantics of the symbolic version specification being available from the project itself ... somehow ...

Dale

|
| frank
|
| > |
| > | > Do we have a convention that each developer create a github
| > | > project
| > | > that provides the version mapping?
| > | >
| > | > Other ideas?
| > | >
| > | > I'll probably be focusing on this issue in the next few days so
| > | > any
| > | > ideas or brainstorming would be greatly appreciated ...
| > | >
| > | > Dale
| > | >
| > | >
| > | > [1] https://github.com/dalehenrich/filetree/tags
| > |
|

another use case where I typically specify a #stable version is when I build a project that is based upon Seaside ...

The project that I am creating is very likely independent of a specific version of Seaside ... it will work with version 3.0.1, 3.0.5, 3.0.7, etc.

If I specify the version of Seaside that is the latest at the time I release a version of my project, then over time, bugfix releases are made for Seaside and I well be compelled to do a new release of my project to pick up the latest versions of Seaside ... otherwise a user of my project won't have the benefit of running with the best version of Seaside available ...

this also applies to platforms ... which version is the last version of Seaside that was known to work on Pharo1.2? If I have a production application running in Pharo1.2 (and it isn't easy to migrate my app to a new image), then I really don't want to have to edit all of the configurations for projects to make sure that they all load the version that works on Pharo1.2 ... using the #stable version insulates you from that problem too ...

Soooo, this is another case where #stable makes a lot of sense ...

The fact that #stable doesn't apply all the time, is why the Metacello scripting API will allow you to pin a version and allow you to say:

  I am using version 3.0.4 of Seaside until further notice...

Dale