GitHub Configs

IIUC, the prefered way to manage GitHub projects via Metacello is to define only a baseline, and then load it via the scripting API. Is that correct?

If so, how does one manage #development and #stable versions?

See the following example...
ConfigurationOfGitFileTree>>version05: spec
...
        spec
                baseline: 'GitFileTree'
                        with: [ spec repository: 'http://smalltalkhub.com/mc/ThierryGoubier/GitFileTreePharo40/main' ];
                import: 'GitFileTree' ]
I guess this configuration is only necessary to adapt to Pharo's current tools (e.g. the Configuration Browser), but won't this always load bleedingEdge? I thought best practice is to only load specific versions from numbered versions. How would one do that here?

On 06/04/2015 08:03 AM, Sean P. DeNigris wrote:
> IIUC, the prefered way to manage GitHub projects via Metacello is to define
> only a baseline,
yes...
> and then load it via the scripting API. Is that correct?
yes.
>
> If so, how does one manage #development and #stable versions?
Good question ... My standard answer to this question would have no
bearing on your example, so I'm not sure that you want an answer to this
question:)

On the off chance that you are only interested in a response to the
following example (which has no bearing on #development or #stable) then
I'll just address the example ... ping me if you want an answer that
addresses the management of #development and #stable versions. I'm not exactly sure why Thierry did things this way ... It may be that
this is a test case for GitFileTree...I think I have one like this as well:)

You are absolutely correct that for an mcz repository a BaselineOf will
always load the #bleedingEdge and is not really that useful. If one is
going to use an mcz repository then one should use a standard
ConfigurationOf and explicitly list the numbered versions of each
package ...

Dale

--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Dale Henrichs-3 wrote

ping me if you want an answer that
addresses the management of #development and #stable versions.

My question arose because I could not figure out what the heck was going on with that configuration. But given that, by your answer, it seems that whatever's going on there is not standard, I guess it doesn't matter much! Although now I'm intrigued... Where can I read about the current best practice for when and how to use Baselines?

In my understanding, you would manage #stable as a tag, then refer to it and #development is just the branch you want, master or whatever… or I’m wrong?


--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

On 06/04/2015 05:53 PM, Sean P. DeNigris wrote:
> Dale Henrichs-3 wrote
>> ping me if you want an answer that
>> addresses the management of #development and #stable versions.
> My question arose because I could not figure out what the heck was going on
> with that configuration. But given that, by your answer, it seems that
> whatever's going on there is not standard, I guess it doesn't matter much!
Haha ... yeah, I wanted to make sure that baselines were not just tied
to directory-based repos, but that didn't mean that there was a good
rationale for the use case:)
> Although now I'm intrigued... Where can I read about the current best
> practice for when and how to use Baselines?
I guess I don't have a write up, but this email may form the basis for one:)

First off, the BaselineOf is intended to be used with git (or mercurial
or ...). When using git, there is no need to track the version numbers
of each of the packages that make up a release, since the git commit of
the entire repository does that for you automatically. The vast bulk of
the ConfigurationOf is dedicated to recording history of older versions
and the baselines associated with the older versions ... The git
repository takes care of managing the complete version history for the
project and all that is needed is the current baseline and that is all
that the BaselineOf does ... when you add/remove a package or change
dependencies you update the BaselineOf in place and then do a git commit
and that's it ...

For the overall workflow, you should look to the web for inspiration and
find a git workflow that matches your needs. [1] and [2] are good places
to start.

With git you have three ways to refer to a commit: branch (master), SHA
(f30ab), tag (v3.1.0), collectively referred to as a commitish. The
github repository spec looks like the following:

github://GsDevKit/gsApplicationTools:<commitish>/repository

The BaselineOf has no explicit version associated with it - you do not
define an explicit version for a baseline instead you use the commitish
as part of the repository spec to identify the "version" of  a dependent
project. Here are some examples:

         spec
           baseline: 'Project1'
           with: [
               spec
                 loads: 'Core';
                 repository:
                     'github://GsDevKit/Project1:master/repository' ];
           baseline: 'Project2'
           with: [
               spec
                 loads: 'Core';
                 repository:
                     'github://GsDevKit/Project2:f30ab/repository' ];
           baseline: 'Project3'
           with: [
               spec
                 loads: 'Core';
                 repository:
                     'github://GsDevKit/Project3:v3.1.0/repository' ].

A branch names a string of commits, when you refer to a branch name in
your spec, you get the latest commit on that branch. In general, this is
the moral equivalent of #bleedingEdge in Metacello.

In the example above, I used the branch name `master`. In my workflow,
the `master` branch represents a rolling release, i.e., the latest
commit on that branch is the latest release for the project, so for _my_
projects, referencing the `master` branch from a project spec is the
moral equivalent of using #stable. I use travis-ci to validate a commit
before it is merged into the master branch (see [2] for more details).

As I have pointed out multiple times in the past, I am not a fan of the
#stable symbolic version because of it's lack of precision (is it
version 3.0.0 or version 4.0.0 that is now stable). For production
applications the project specs for dependent projects needs to have a
finer granularity for versions.

In git the SHA is the ultimate in version granularity as you are
referencing a specific commit and there is no ambiguity whatsoever. The
disadvantage for using a SHA in a project spec is that you will find
yourself updating your configurations every time a project publishes a
bugfix. There is no moral equivalent to a SHA in the mcz repository
universe - unless you are looking at a single package project.

In git a tag is a name for a SHA, the tag shares the disadvantages of a
SHA, but at least you can use the tag to provide a version number and if
you follow the Semantic Versioning specification[3], then the version
name imparts a bit more information about the particular commit than a
naked SHA. The version in a ConfigurationOf is the moral equivalent of a
tagged commit. A tag in git can be changed to point to a different SHA
just as a version in a ConfigurationOf can be changed by a developer ...
this is frowned upon but allowed.

As an alternative to using #stable symbolic versions, I have advocated
for the convention used by the Seaside folks, where they have a set of
symbolic versions: #release3, #release31, #release311, #release32, etc.  
With each new release they name the new version appropriately (i.e.,
3.1.2) and update the appropriate symbolic versions (in this case
#release3, #release31 and #release312) to point to this new version.
This gives dependent project a choice as to the level of granularity
that they are comfortable with and they can avoid having to update their
own configuration every time a new version is published.

git does not have symbolic versions, so the notion of tag pattern
matching was introduced (see this issue comment [4] fo details). Given
the following repository spec:

   github://GsDevKit/Project3:v3.1.0/repository

this is equivalent to the #release3 symbolic version:

   github://GsDevKit/Project3:v3.?/repository

this is equivalent to the #release31 symbolic version:

   github://GsDevKit/Project3:v3.1.?/repository

this is equivalent to the #release311 symbolic version:

   github://GsDevKit/Project3:v3.1.1?/repository

Finally, to replace a #development symbolic version, I suggest that you
use something like a shared development topic branch[5] where the latest
commit on the topic branch is the #development version. Individual
developers would work on a separate topic branches and when their unit
of work is complete they would merge into the `dev` branch where other
developers can pick up the work ...

I think that covers most of issues... Questions?

Dale

[1] http://nvie.com/posts/a-successful-git-branching-model/
[2] https://help.github.com/articles/what-is-a-good-git-workflow
[3] http://semver.org/
[4]
https://github.com/dalehenrich/metacello-work/issues/277#issuecomment-58947282
[5] http://fiji.sc/Git_topic_branches

--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

That was very thorough and gave a nice overall view. Thanks!

Dale Henrichs-3 wrote

A branch... is the moral equivalent of #bleedingEdge in Metacello.

Okay, yes that part seems pretty straightforward...

Dale Henrichs-3 wrote

I am not a fan of the #stable symbolic version because... dependent projects needs to have a
finer granularity for versions.

IOW, maybe I want to say, depend on the latest version backward-compatible with my current version e.g. 3.1.x, but #stable doesn't allow that flexibility.

Dale Henrichs-3 wrote

A tag in git can be changed to point to a different SHA...

So if you wanted to mimic #stable behavior (not that I'm recommending that), one would keep reassigning the stable tag to different SHAs. Is that right?

Dale Henrichs-3 wrote

I have advocated for the convention used by the Seaside folks, where they have a set of
symbolic versions: #release3, #release31, #release311, #release32, etc.  

Forcing this extra work on users seems like we are not capturing some abstraction. If a dev commits to semantic versioning, can't Metacello offer looser matching like you describe for git below (e.g. '3.1.?')?

On 06/07/2015 07:53 AM, Sean P. DeNigris wrote: Yeah that's the fundamental problem ... #stable has been used to cross
major version boundaries which wreaks havoc on projects written against
older versions ... the abandonment of old platforms is also a problem
... #stable has come to mean the latest version of the project that runs
on the currently latest version of Pharo Only...alll other users beware:)
>
>
> Dale Henrichs-3 wrote
>> A tag in git can be changed to point to a different SHA...
> So if you wanted to mimic #stable behavior (not that I'm recommending that),
> one would keep reassigning the stable tag to different SHAs. Is that right?
Actually pointing at the master branch is a good simulation of #stable
(modulo the platform designation)
The #~> operator for versions[1] has been in existence since the beginning:

    '1.1' ~> version     gives same result as: '1.1' <= version < '2.0'
    '1.1.0' ~> version  gives same result as: '1.1' <= version < '1.2'

and so on ... you can even set the operator in your project spec:

         spec
           configuration: 'Project1'
           with: [
               spec
                 version: '1.1.0';
                 operator: #~>;
                 loads: 'Core';
                 repository:
                     'http://example.com/mczRepository' ].

however I think that the current semantics  of this statement is that
version '1.1.0' will be loaded. Then (while using the Scripting API), if
another project attempts to load a later version of the project outside
the "accepted range" a version conflict will signalled ....

So as currently implemented, this doesn't quite do what we'd want which
is to initially load the latest version from ConfigurationOfProject1
that is within the range... Given the fact that I don't think that
twiddle-thwacka is in wide usage, I'd be willing to tweak the version
lookup scheme to support the (potentially) desired semantics for #~> or
perhaps support a different scheme altogether:) Perhaps the time has
come where there is sufficient interest?

With that said, I think that within the ConfigurationOf universe the
#release* symbolic version provides  almost exactly the same semantics
as the desired behavior of #~> operator, so I'm not sure that a new
feature is actually called for....

The onus for following some variant of semantic versioning is on the
project developers themselves, so I'm not sure that updating a handful
of #release* symbolic versions  really classifies as that much "extra
work":) ... and the "abstraction to be captured" is that projects need
to START following semantic versioning!

When project developers who are using semantic versioning begin
complaining the #release* doesn't quite meet their needs, I will be all
ears:)

Dale

[1] https://robots.thoughtbot.com/rubys-pessimistic-operator


--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Sean,

In the shower this morning I imagined that an alternate implementation
would be to allow a simple block to be specified  in a project reference:

         spec
           configuration: 'Project1'
           with: [
               spec
                 versionSelectBlock: [ :version |
                     '1.1' asMetacelloVersionNumber <= version
                          and: [ version < '2.0'
asMetacelloVersionNumber ] ];
                 loads: 'Core';
                 repository:
                     'http://example.com/mczRepository' ].

The versionSelectBlock would be applied to the available versions in
ConfigurationOfProject1 and then the latest of those versions would
become the "resolved version" for loading and comparison purposes
similar to how symbolic versions are handled today ... the fact that
this approach is similar enough to symbolic versions significantly
reduces the implementation and test costs (as compared to making #~>
work correctly) means that I would be inclined to implement this
approach if there were sufficient interest:)

Dale

On 06/08/2015 11:59 AM, Dale Henrichs wrote:
--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Dale Henrichs-3 wrote

I think that covers most of issues... Questions?

IIUC my biggest revelation is so far is: because the baseline is committed along side the rest of the git repo, you only need the current package relationships, because by the time you have the baseline, you've already specified its particular Git commit.

Now, as for also having a Configuration, I think:
a. you don't need one because you can use the Metacello scripting API load the #baseline:
b. the main reason you might want one is to interface with current tools

I am tripping over two points:
1. IMHO embedding the commitish in the repository name creates a barrier for non-Git-ers. Imagine I want to load version 3.2.1 of someone's project (i.e. they have tagged such a release). I can't just paste the clone URL from GitHub. I have to then remember where to insert the commitish. Would it be possible to reuse the familiar #version: message e.g.:
  Metacello new
    baseline: 'Sample';
    repository: 'github://dalehenrich/sample/repository';
    version: '0.8.0';
    load.
2. Assuming that #a above was correct, I am still not clear what happens to #bleedingEdge (admittedly this one seems the least relevant in a Git world), #development, and #stable. As you mentioned, how those map depends on the Git development workflow of the project. As a user, I can't assume that everyone treats master as #stable the way you do. An inexperienced dev might treat master more like #bleedingEdge! Can one, for example, in a ConfigurationOfXyz which uses a BaseLineOfXyz, map #development to master? I tried a few ways but couldn't get it to work...

On 08/05/2015 10:20 AM, Sean P. DeNigris wrote:
> Dale Henrichs-3 wrote
>> I think that covers most of issues... Questions?
> IIUC my biggest revelation is so far is: because the baseline is committed
> along side the rest of the git repo, you only need the current package
> relationships, because by the time you have the baseline, you've already
> specified its particular Git commit.
exactly!
>
> Now, as for also having a Configuration, I think:
> a. you don't need one because you can use the Metacello scripting API load
> the #baseline:
correct ...
> b. the main reason you might want one is to interface with current tools
Not sure what you mean here ... if you are talking about tools that are
based on configurations then yes, but I'm not sure which ones those  
would be ... versioner?

I have to use configurations for bootstrapping the github based
Metacello Preview and you can see how I create github versions in a
configuration[1]

[1]
https://github.com/dalehenrich/metacello-work/tree/configuration/ConfigurationOfMetacelloPreview.package/ConfigurationOfMetacelloPreview.class/instanceThis is a good point and I think this wanders into the territory of
using tags with git ... if you look at the tags for the
GsDevKit/Seaside31 project  on github you will see that we are naming a
commitish with a familiar version string like 3.1.4.1-gs (the -gs isn't
really necessary ... I use a more conventional set of version names for
the gsApplicationTools tags[3])

For the sample project in your example, I've defined a 0.8.0 tag[4] and
here's the way to reference a tag for loading:

   Metacello new
     baseline: 'Sample';
     repository: 'github://dalehenrich/sample:0.8.0/repository';
     load.


[2] https://github.com/GsDevKit/Seaside31/releases
[3] https://github.com/GsDevKit/gsApplicationTools/releases
[4] https://github.com/dalehenrich/sample/releases
> 2. Assuming that #a above was correct, I am still not clear what happens to
> #bleedingEdge (admittedly this one seems the least relevant in a Git world),
> #development, and #stable. As you mentioned, how those map depends on the
> Git development workflow of the project. As a user, I can't assume that
> everyone treats master as #stable the way you do. An inexperienced dev might
> treat master more like #bleedingEdge! Can one, for example, in a
> ConfigurationOfXyz which uses a BaseLineOfXyz, map #development to master? I
> tried a few ways but couldn't get it to work...

For symbolic versions we're basically using tag pattern matching ...

#bleedingEdge is handled by referencing a branch name:

   Metacello new
     baseline: 'Sample';
     repository: 'github://dalehenrich/sample:master/repository';
     load.

ends up referencing the most recent commit on the master branch ...
moral equivalent of #bleedingEdge ... but better, since you can use a
topic branch (like issue_3) to fix a bug and then combined with travis
and pull requests you can ensure that the latest commit on master has
passed all of the tests and been reviewed ... so this is useful for
continuous releases ...

You have a good point with regards to using #stable ... there are too
many interpretations there ... a better approach is used by the Seaside
folks where they define symbolic versions like: #release3, #release31
and #release32 to allow one to specify that you want to use the latest
3.x version, 3.1 version or 3.1 version.

With git you accomplish this with  tag pattern matching[5].  To match
all 3.x versions/tags you'd do the following:

   Metacello new
     baseline: 'Sample';
     repository: 'github://dalehenrich/sample:3.?/repository';
     load.

for the latest 3.1 you'd do the following:

   Metacello new
     baseline: 'Sample';
     repository: 'github://dalehenrich/sample:3.1.?/repository';
     load.

and so on ...

Dale


[5]
https://github.com/dalehenrich/metacello-work/issues/277#issuecomment-58970696

--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Dale Henrichs-3 wrote

> Now, as for also having a Configuration, I think:
...
> b. the main reason you might want one is to interface with current tools
if you are talking about tools that are based on configurations then yes, but I'm not sure which ones those  
would be ... versioner?

I was thinking of the Configuration Browser, which seems to be become the de facto project loading standard in Pharo, and is being replaced by its more powerful brother the Catalog Browser.

Dale Henrichs-3 wrote

>    Metacello new
>      baseline: 'Sample';
>      repository: 'github://dalehenrich/sample/repository';
>      version: '0.8.0';
>      load.
...
   Metacello new
     baseline: 'Sample';
     repository: 'github://dalehenrich/sample:0.8.0/repository';
     load.

Yes, that is the API I'm objecting to ;) I'm wondering if we can allow my non-working version be equivalent to your version so that Git newbies don't have to remember the intricacies of github URLs and can use the dedicated API they're used to for non-Git things to specify the commitish.

Dale Henrichs-3 wrote

> ... I am still not clear what happens to
> #bleedingEdge (admittedly this one seems the least relevant in a Git world),
> #development, and #stable.
...
Metacello new
     baseline: 'Sample';
     repository: 'github://dalehenrich/sample:master/repository';
     load.

Sorry, I wasn't clear. I meant how do we handle symbolic versions in the context of Configurations so that projects can still be loaded via e.g. the Configuration Browser, at least for the time being since we'll be living with Pharo 4.0 for 6 months. How do we do the same things you showed with the scripting API, but embedded in a configuration. I tried creating a non-numeric version i.e. `<version: 'dev'>` in which I referenced the master branch, and which I referenced like `<symbolicVersion: #development>... spec for: #common version: 'dev'`, but Metacello was not happy about that! It seems it expected a number and was trying to compare 'dev'...

Thanks for talking this through with me. I was excited to see how well the BaselineOf fits in with git and relieves much complexity :)

On 08/06/2015 01:59 PM, Sean P. DeNigris wrote: Okay ... I haven't been following the evolution of Pharo recently, so
I'm clearly out of the loop:) It _could_ be done, but it would take a lot of monkey business to fake
things out ....

when you use a baseline with a filetree repo there is absolutely no such
thing as version so I'm not comfortable introducing the notion of a
version for baselines when they really don't have a version associated
with them.

the real version for a baseline is dictated by the underlying disk
structure and the url is used to download the correct disk contents, so
the baseline is not "aware" that a github repo is involved here ...

I am sympathetic to your concerns but using git and github is going to
require that a newbie understand more than a change in how you specify a
version for Metacello and I do think that the url fits more with how
git/github integrate into Metacello ...

We can talk about this more, so don't surrender too easily:) But the one
thing that sticks out in my mind is that a "baseline does not have a
version" ... directories can be switched out from underneath a FileTree
repository without "informing the image" so it is important to realize
that the Baseline is a object from the disk and unlike a Configuration
does not stand alone ...
Well if you are going to use a configuration then take a look at the
ConfigurationOfMetacelloPreview[1]. You specify a version that directly
references a particular commitish of the github repo and once you've
defined versions. (no baseline:). You can then use symbolic versions on
those versions ... The `import:` method allows you to import all of the
names from the baseline so that you can reference a
package/group/project just like in a regular configuration version ...

[1]
https://github.com/dalehenrich/metacello-work/tree/configuration/ConfigurationOfMetacelloPreview.package/ConfigurationOfMetacelloPreview.class/instance 

>
> Thanks for talking this through with me. I was excited to see how well the
> BaselineOf fits in with git and relieves much complexity :)
>
No problem. I really appreciate your questions and your perspective ...
A lot of the changes to Metacello for working with git/github had to be
made without being able to consult with another person, since I was the
only person working in the area and in the beginning I was not a
git/github expert so I had to stumble alone for a while and feel my way
around ... so I appreciate the fact that you are educating yourself and
stumbling around and asking questions to keep me honest and to provide a
slightly different viewpoint that is very valuable!

The combo of git and a BaselineOf is so simple to use it's why I've
"moved on" from Monticello repositories ... having branches and
multi-package merges and non-code artifacts are additional advantages of
git that I choose not to live without:)

Dale

--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Dale Henrichs-3 wrote

We can talk about this more, so don't surrender too easily:)

Okay, let's just call a ceasefire while I mull ;)

Dale Henrichs-3 wrote

Well if you are going to use a configuration then take a look at the
ConfigurationOfMetacelloPreview[1]

I did and I'm most of the way toward a solution. The missing piece is what do I put in `<version: '???'>` for a version that references the master branch. A number doesn't make sense, but Metacello choked on a string there.

Dale Henrichs-3 wrote

I really appreciate your questions and your perspective ...

Great, I'll keep them coming!

On 08/06/2015 03:25 PM, Sean P. DeNigris wrote:
> Dale Henrichs-3 wrote
>> Well if you are going to use a configuration then take a look at the
>> ConfigurationOfMetacelloPreview[1]
> I did and I'm most of the way toward a solution. The missing piece is what
> do I put in `<version: '???'>` for a version that references the master
> branch. A number doesn't make sense, but Metacello choked on a string there.
>
Ah, was your configuration a subclass of ConfigurationOf? If so the
default ConfigurationOf>>versionNumberClass is
MetacelloSemanticVersionNumber, if you override the method and use
MetacelloVersionNumber as the versionNumberClass, you should be allowed
to use a simple string for a version number...

Dale

--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.

Dale Henrichs-3 wrote

Ah, was your configuration a subclass of ConfigurationOf? If so... use
MetacelloVersionNumber as the versionNumberClass

That seems to have done the trick. Thanks!

p.s. looks like we'll see each other in Portland soon

On 08/06/2015 06:05 PM, Sean P. DeNigris wrote:
> Dale Henrichs-3 wrote
>> Ah, was your configuration a subclass of ConfigurationOf? If so... use
>> MetacelloVersionNumber as the versionNumberClass
> That seems to have done the trick. Thanks!
good...
>
> p.s. looks like we'll see each other in Portland soon
That's right  ... the Camp Smalltalk is coming up ... I am looking
forward to seeing you again!

--
You received this message because you are subscribed to the Google Groups "Metacello" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
For more options, visit https://groups.google.com/d/optout.