Pharo 7 - New Iceberg feedback

Hi,

I'll take some minutes to provide an answer as detailed as possible to all questions in this mail, and to the ones in the mails before.

But first, since I know most people only read the first lines of mails :P, if you find any concrete iceberg issues, please report them in 

https://github.com/pharo-vcs/iceberg/issues

Now, answers inline.

On Tue, May 22, 2018 at 5:15 PM, Tim Mackinnon <[hidden email]> wrote:

Hi - last night we managed to explore the new contribution process as well as the new iceberg ui at the U.K. Smalltalk meetup last night.

Cool!

 

Not many had seen it before so it was a good test run.

As an initial comment - we need to invest a small amount of time to get the right docs in places you expect them as not doing so undoes a lot of good work -  the Pharo main site that points to old contribution docs (and doesn’t reference the new ones) must be updated ASAP to keep energy high (we almost lost a few folks last night by going down the wrong path - fortunately Cyril piped up on Discord for me - phew).

I know. This is indeed important. I'm trying to get time to make videos, paste as much info in the wiki. Now, it would be good to know what was exactly your "wrong path". The more concrete you are, the easier is to fix it :).

I see Pharo contribution page (http://pharo.org/contribute-propose-fix) points to https://github.com/pharo-project/pharo/wiki/Contribute-a-fix-to-Pharo which is outdated. I'll fix it ASAP.

 

Armed with the right steps it was straightforward - much easier than the older slices mechanism (that I never was comfortable with) - so HUGE thanks for that everyone!

As we worked through it, the more git seasoned folks were confused why git status in a terminal wasn’t really showing the same info as iceberg (I’ll put this in a separate thread to discuss, as it’s an interesting thought which I’m sure has lively discussion).

Well, this is the discussion in the other thread. If you have read the glosssary (https://github.com/pharo-vcs/iceberg/wiki/Iceberg-glossary), you will notice that iceberg presents you with two working copies:

  - the image working copy

  - the disk working copy

The disk working copy is what most people know when they use git. The directory where you have your repository, with the files you're modifying.

The image working copy represent what is loaded in Pharo. It's important to differentiate them because if I send you an image (or you download it from somewhere) you have code loaded on it. This working copy allows us to track how and where you loaded that code from. That is useful if later on you want to contribute to that project in some way.

Then there are other questions:

!! Why do we still have a disk working copy?

Well, this is not really necessary for iceberg to work. Iceberg could just write source code directly on git's BLOB, as Thierry mentioned in the other thread.

The reason for this working copy to be there is just to try to be less alien.

Having the disk working copy allows people to still have a way to:

  - edit non-smalltalk files from the command like

  - use the non command line as a last ressource if something goes wrong with your Pharo image

  - use external tools to manage the repository (sourcetree, git kraken, whatever you're confortable with)

The idea is that Iceberg will try to keep your disk working copy in sync with your repository HEAD.

It will take care of transparently synchronizing your disk working copy when:

 - you commit

 - you change branches

 - you pull/push/merge

!! Why don't we dump code into the disk as we write it?

The main reason behind it is that the image is not causally connected to the directory in disk, as Ben implied.

There is not a 1 to 1 correspondence between what you could ever have in disk and your running image.

As Ben mentionned, for this to happen:

 - changing the source code in disk should get automatically loaded into Pharo

 - changing the source code in Pharo should get automatically written in disk

The thing is that this is much more difficult than it sounds:

 - What happens if you do not want to save your image, you forgot to save it or it crashes? Suddenly you will have an image that is not in sync with your repository. Would you load all changes into your image as soon as you reopen it? Atomically?

 - What happens if you share your repository between several images?

 - Or if suddenly you change your branch from the command line to something completely different?

Several of these usecases don't even make sense. So we preferred to choose the path of "make it explicit".

Of course, we could do better, we are open to discuss any improvements.

Just take into account that Iceberg did not come from an egg :) we have thought about many possible scenarios and discussed with a lot of people before.

!! How does merge work?

First, just for the record, merge works. We even

 - detect fast forward merge avoiding the creation of extra merge commits

 - proposing a single UI to resolve all conflicts of a project at once and not one per package

Now, as Thierry suggested in the other thread, Iceberg's merge happen in memory. The reason behind this is that using Git's default merge mechanism would insert the >>>> <<<< markers in the conflicting files. This would break our parsers and all our tools.

Instead, we ask git for the list of conflicting files, and we build a diff tree in memory, that we later augment with information such as conflicts.

There are some issues we have seen when merging external files, but as soon as the two merged commits are not merging external files, but we hope we will fix them soon.

Missing feature: right now we can only choose between incoming or loaded version during a merge. It would be nice to be able to edit a method's code, picking part of the incoming code and part of the current code.

Missing feature 2: right now we resolve all conflicts in memory and commit them at once. We know some people would like to, instead, not do the merge automatically, so they can test it before committing. This should not be tooo difficult to do but it was down in the priority list :).

!! Exporting without commiting?

There is no UI support for this, but it is doable from the backend, though not correctly exposed right now.

You can right-click on the repository -> Extras -> Inspect

repository index updateDiskWorkingCopy: repository workingCopy workingCopyDiff.

Anyway - the new UI does take some getting used to (personally I liked the compactness of the original Iceberg and its tabs), but when you understand what the different windows show you - I think it makes sense (and hopefully is more stable).

Well, the UI rewriting has several ideas behind. I'll put whichever ones come to my mind in here, I hope Esteban will correct me if I'm wrong:

 - Moving from Glamour to Spec. This is a purely technical decision. AFAIK, maybe I'm wrong, Glamour is not being maintained anymore by the GT team, and it has some rough corners that made the old UI difficult to deal with sometimes. From an investment of time standpoint, we decided to put effort in Spec instead...

 - Simplify the UI. We needed it to be less overwhelming and sometimes more direct. That's the why of the toolbar on the top, and the more (but smaller and simpler) windows.

Regarding the design, Esteban followed some UI guidelines for the design taken from I don't where. But at the end we are engineers, not UI designers, so we make ugly UIs by default :P.

Any improvement or concrete suggestion on this direction is welcome :).

 

We all missed having an obvious Diff mechanism - we later spotted that Commit does show this (Although possibly calling it “Commit…” might make it more obvious that you have a chance to review changes and change your mind) - but knowing the size of your change and reviewing them without any danger of committing something is a useful feature (but maybe a 2.0 enhancement request?).

Yes, I want that also. I miss 

- a Diff/See Changes button.

- that the tabs that show the diffs should maybe say "Diff: XXX to YYY" instead of just "XXX to YYY"

Could you open an issue?

 

One small tweak (which I would PR if I knew how to - would be to swap  the status and branch columns in the Repository window  to make the status  clearer (the status gets lost as it sqashed against the normally much longer branch name).  Its a simple change to #initializeRepositoryList but I guess Iceberg is in a different repository (and not in the instructions for contirbutions).

Could you open an issue?

 

We also noticed that if you try to use the “Create Pull Request” menu item, you can’t if you have 2FA enabled on Github (the recommended setting) as I guess that ssh protocol doesn’t allow this with an ssh key? So I we should update the instructions to suggest either using the web ui - or - creating an app specific login (that doesn’t use 2fa). - I’ll look at how to add that tweak and send a PR.

Ouki :)

Thanks!

 

Tim


Sent from my iPhone

--

Guille Polito Research Engineer Centre de Recherche en Informatique, Signal et Automatique de Lille CRIStAL - UMR 9189 French National Center for Scientific Research - http://www.cnrs.fr Web: http://guillep.github.io Phone: +33 06 52 70 66 13

https://github.com/pharo-vcs/iceberg/wiki/The-Working-Copy(ies)

https://github.com/pharo-vcs/iceberg/wiki/Branching-and-Merging

On Thu, May 24, 2018 at 11:30 AM, Guillermo Polito <[hidden email]> wrote:

Hi,

I'll take some minutes to provide an answer as detailed as possible to all questions in this mail, and to the ones in the mails before.

But first, since I know most people only read the first lines of mails :P, if you find any concrete iceberg issues, please report them in 

https://github.com/pharo-vcs/iceberg/issues

Now, answers inline.

On Tue, May 22, 2018 at 5:15 PM, Tim Mackinnon <[hidden email]> wrote:

Hi - last night we managed to explore the new contribution process as well as the new iceberg ui at the U.K. Smalltalk meetup last night.

Cool!

 

Not many had seen it before so it was a good test run.

As an initial comment - we need to invest a small amount of time to get the right docs in places you expect them as not doing so undoes a lot of good work -  the Pharo main site that points to old contribution docs (and doesn’t reference the new ones) must be updated ASAP to keep energy high (we almost lost a few folks last night by going down the wrong path - fortunately Cyril piped up on Discord for me - phew).

I know. This is indeed important. I'm trying to get time to make videos, paste as much info in the wiki. Now, it would be good to know what was exactly your "wrong path". The more concrete you are, the easier is to fix it :).

I see Pharo contribution page (http://pharo.org/contribute-propose-fix) points to https://github.com/pharo-project/pharo/wiki/Contribute-a-fix-to-Pharo which is outdated. I'll fix it ASAP.

 

Armed with the right steps it was straightforward - much easier than the older slices mechanism (that I never was comfortable with) - so HUGE thanks for that everyone!

As we worked through it, the more git seasoned folks were confused why git status in a terminal wasn’t really showing the same info as iceberg (I’ll put this in a separate thread to discuss, as it’s an interesting thought which I’m sure has lively discussion).

Well, this is the discussion in the other thread. If you have read the glosssary (https://github.com/pharo-vcs/iceberg/wiki/Iceberg-glossary), you will notice that iceberg presents you with two working copies:

  - the image working copy

  - the disk working copy

The disk working copy is what most people know when they use git. The directory where you have your repository, with the files you're modifying.

The image working copy represent what is loaded in Pharo. It's important to differentiate them because if I send you an image (or you download it from somewhere) you have code loaded on it. This working copy allows us to track how and where you loaded that code from. That is useful if later on you want to contribute to that project in some way.

Then there are other questions:

!! Why do we still have a disk working copy?

Well, this is not really necessary for iceberg to work. Iceberg could just write source code directly on git's BLOB, as Thierry mentioned in the other thread.

The reason for this working copy to be there is just to try to be less alien.

Having the disk working copy allows people to still have a way to:

  - edit non-smalltalk files from the command like

  - use the non command line as a last ressource if something goes wrong with your Pharo image

  - use external tools to manage the repository (sourcetree, git kraken, whatever you're confortable with)

The idea is that Iceberg will try to keep your disk working copy in sync with your repository HEAD.

It will take care of transparently synchronizing your disk working copy when:

 - you commit

 - you change branches

 - you pull/push/merge

!! Why don't we dump code into the disk as we write it?

The main reason behind it is that the image is not causally connected to the directory in disk, as Ben implied.

There is not a 1 to 1 correspondence between what you could ever have in disk and your running image.

As Ben mentionned, for this to happen:

 - changing the source code in disk should get automatically loaded into Pharo

 - changing the source code in Pharo should get automatically written in disk

The thing is that this is much more difficult than it sounds:

 - What happens if you do not want to save your image, you forgot to save it or it crashes? Suddenly you will have an image that is not in sync with your repository. Would you load all changes into your image as soon as you reopen it? Atomically?

 - What happens if you share your repository between several images?

 - Or if suddenly you change your branch from the command line to something completely different?

Several of these usecases don't even make sense. So we preferred to choose the path of "make it explicit".

Of course, we could do better, we are open to discuss any improvements.

Just take into account that Iceberg did not come from an egg :) we have thought about many possible scenarios and discussed with a lot of people before.

!! How does merge work?

First, just for the record, merge works. We even

 - detect fast forward merge avoiding the creation of extra merge commits

 - proposing a single UI to resolve all conflicts of a project at once and not one per package

Now, as Thierry suggested in the other thread, Iceberg's merge happen in memory. The reason behind this is that using Git's default merge mechanism would insert the >>>> <<<< markers in the conflicting files. This would break our parsers and all our tools.

Instead, we ask git for the list of conflicting files, and we build a diff tree in memory, that we later augment with information such as conflicts.

There are some issues we have seen when merging external files, but as soon as the two merged commits are not merging external files, but we hope we will fix them soon.

Missing feature: right now we can only choose between incoming or loaded version during a merge. It would be nice to be able to edit a method's code, picking part of the incoming code and part of the current code.

Missing feature 2: right now we resolve all conflicts in memory and commit them at once. We know some people would like to, instead, not do the merge automatically, so they can test it before committing. This should not be tooo difficult to do but it was down in the priority list :).

!! Exporting without commiting?

There is no UI support for this, but it is doable from the backend, though not correctly exposed right now.

You can right-click on the repository -> Extras -> Inspect

repository index updateDiskWorkingCopy: repository workingCopy workingCopyDiff.

Anyway - the new UI does take some getting used to (personally I liked the compactness of the original Iceberg and its tabs), but when you understand what the different windows show you - I think it makes sense (and hopefully is more stable).

Well, the UI rewriting has several ideas behind. I'll put whichever ones come to my mind in here, I hope Esteban will correct me if I'm wrong:

 - Moving from Glamour to Spec. This is a purely technical decision. AFAIK, maybe I'm wrong, Glamour is not being maintained anymore by the GT team, and it has some rough corners that made the old UI difficult to deal with sometimes. From an investment of time standpoint, we decided to put effort in Spec instead...

 - Simplify the UI. We needed it to be less overwhelming and sometimes more direct. That's the why of the toolbar on the top, and the more (but smaller and simpler) windows.

Regarding the design, Esteban followed some UI guidelines for the design taken from I don't where. But at the end we are engineers, not UI designers, so we make ugly UIs by default :P.

Any improvement or concrete suggestion on this direction is welcome :).

 

We all missed having an obvious Diff mechanism - we later spotted that Commit does show this (Although possibly calling it “Commit…” might make it more obvious that you have a chance to review changes and change your mind) - but knowing the size of your change and reviewing them without any danger of committing something is a useful feature (but maybe a 2.0 enhancement request?).

Yes, I want that also. I miss 

- a Diff/See Changes button.

- that the tabs that show the diffs should maybe say "Diff: XXX to YYY" instead of just "XXX to YYY"

Could you open an issue?

 

One small tweak (which I would PR if I knew how to - would be to swap  the status and branch columns in the Repository window  to make the status  clearer (the status gets lost as it sqashed against the normally much longer branch name).  Its a simple change to #initializeRepositoryList but I guess Iceberg is in a different repository (and not in the instructions for contirbutions).

Could you open an issue?

 

We also noticed that if you try to use the “Create Pull Request” menu item, you can’t if you have 2FA enabled on Github (the recommended setting) as I guess that ssh protocol doesn’t allow this with an ssh key? So I we should update the instructions to suggest either using the web ui - or - creating an app specific login (that doesn’t use 2fa). - I’ll look at how to add that tweak and send a PR.

Ouki :)

Thanks!

 

Tim


Sent from my iPhone

--

Guille Polito Research Engineer Centre de Recherche en Informatique, Signal et Automatique de Lille CRIStAL - UMR 9189 French National Center for Scientific Research - http://www.cnrs.fr Web: http://guillep.github.io Phone: +33 06 52 70 66 13

--

Guille Polito Research Engineer Centre de Recherche en Informatique, Signal et Automatique de Lille CRIStAL - UMR 9189 French National Center for Scientific Research - http://www.cnrs.fr Web: http://guillep.github.io Phone: +33 06 52 70 66 13