Integration detail history table, no context to know what revision to deploy

[gashcrumb]

Now that I've implemented the buttons that basically let you roll back an integration I noticed that the history table is kinda hard to use :-)

For example, here's 9 revisions, what did I do in them:

The trouble is with no context there's no way to know what revision I want to pick.

Granted, we're currently lacking some data to show real numbers for 'uses' and for the 'success'/'error' column there which will help, but I wonder if we should show perhaps the commit message? Ideally if we generate intelligent commit messages that kinda indicate what changes were made to the integration then we could show them in this table.

@iocanel @dongniwang FYI...

[dongniwang]

Having the success/error states would help, when you say commit messages, what do they look like? Are they like JIRA activities or the GitHub events?

My concern is how are we defining "versions", and what do we count as "revisions"...I can see we easily have dozens of revisions...then we need to introduce pagination and perhaps search/filter?

[gashcrumb]

So every save operation is effectively a revision I believe, i.e. when you click 'save as draft' or 'publish'. Not sure on what the generated commit messages look like, we should definitely work to make them usable if they're not. With the data shown in the table, filtering isn't going to be very useful, like how would filtering on 'times used' help? :-)

We could consider having a prompt for a commit message as part of saving perhaps that could then be used as part of the revision history, or perhaps better still, doing a 'publish' vs a 'save' is what bumps the revision history, and maybe we should require a message on a publish.

[dongniwang]

Hmm..do you mean the backend would generate some kind of commit messages for every save operation? Having a prompt commit message is not a bad idea consider that's a common concept of version control.

I'm not sure how 'save' and 'publish' should affect the revision history...I can see value in having a version for the 'save as draft' operation - e.g. an expert users create a draft integration and hand off to a citizen developer. The draft version would be something useful to have in this case.

[gashcrumb]

Yeah, it's almost like we want a 'tag' operation to tag the current deployed version, or something along those lines.

@iocanel or @jimmidyson or @rhuss any thoughts?

[rhuss]

@gashcrumb @dongniwang The initial idea as described in https://github.com/syndesisio/syndesis-project/blob/master/proposals/044-integration-model.md#versioning and https://github.com/syndesisio/syndesis-project/blob/master/proposals/044-integration-model.md#deployment-of-an-integration-revision was that:

• When you "Save" a draft version it only lives in the Syndesis DB. There is no versioning between various steps between save actions on a draft revision. There is no interaction with Git for saving a draft revision.
• When you "Publish" a draft, then the idea was to create a new branch in the Git repository (named after the revision). That way an expert user can later continue to work on this branch, revision.
• Switching between revisions means switching between Git branches in the runtime.
• The revision running would be always the 'HEAD" of the revision branch.

Does this makes sense ?

[dongniwang]

@rhuss Yes, it makes perfect sense with your explanation using the Git language. But I'm not sure this is clear to our users, especially the citizen users.

Would it be helpful to place a help icon/info icon next to "History" to provide additional info on these concepts?

cc: @sjcox-rh

[iocanel]

My understanding is that what we see in the list is the result of a bug, that kept spawning clones of the draft revision. The fix for was merged yesterday, so I am wondering if this is still an issue.

[gashcrumb]

I think we should still maybe consider if the current design of the table helps the user understand what actions can be performed from it and what the result of those actions will be. Even with Roland's description as a user I have no indication when selecting another revision to deploy exactly what state that revision was in, I'd have to remember that revision x had y steps in it, which doesn't seem ideal.

Wonder if deploying a previous revision needs to be a 2-click process, i.e. you click deploy, the page prompts you with a visualization of the integration from that revision as an 'are you sure?' prompt.

[dongniwang]

@gashcrumb good point. I think there're two things we can do:

• Can we display something similar to the integration list page? So for each version, we can include the connection icons? Maybe we need to find a way to include the steps because those are the real differentiators...
  

• Like what @gashcrumb said, need to display a modal dialogue with the visualization of the integration. See screenshot below. I'm still thinking what's the best way to prompt users as I don't think bringing them to another page would help.
  

[gashcrumb]

Yeah, each revision includes the steps so either approach could be used.

I think showing a visualization per line could get a bit visually noisy? But I can give it a try and we can see what we think, as I think it's really the only indicator why a line in the revision table is there.

If it's too much then I think the modal approach would be a good approach as well.

[dongniwang]

And actually when users perform a re-deploy action, there should be some kind of confirmation message. So having a modal may not be a bad idea.

[dongniwang]

I think showing a visualization per line could get a bit visually noisy?

If users only have a few steps for that integration, it's probably fine. But I'm worried that once they have more than 2 or 3 steps...the table row is going to be very crowded.

[gashcrumb]

If users only have a few steps for that integration, it's probably fine, But I'm worried that once they have more than 2 or 3 steps...the table row is going to be very crowded.

Exactly, and that's a hard view to figure out how to truncate properly while still showing useful information. Modal is sounding better :-)

[sjcox-rh]

Yeah I'm not sure showing a visual for each version is a great idea, that would get tricky, especially if we want to show all the steps.

Also, I know this doesn't solve the issue of differentiating each version, but are we still planning on showing a tag for the version that's currently running?

[dongniwang]

Copying @rhuss comment from another document to keep all the integration history/version/life cycle handling discussion in one place.

Actually the idea was that an integration revision can not be edited after it has been publish (it becomes immutable after publish to keep the history and make the sync between runtime and definition possible).

Instead, when you wan to change an integration revision you create a new draft. This can be done from scratch or by duplicating an existing integration revision. As soon as you publish the draft it becomes a new integration revision (with a new number) which can't be change again.

Of course this can be handled transparently, so that from a user pov you still can say "edit" but under the hoods it will clone the revision to draft and then you can edit it. (However there would be a problem if there is already a draft which then would be overwritten as there can be only a single draft).

tl;dr -- If its about editing the top level integration params, the popup is fine (name and description of an integration doesn't affect the runtime anyway). If its about a revision, technically its a bit different, but probably still ok ;-)

[dongniwang]

So @sjcox-rh @amysueg and I had a discussion about this and came up with a few solutions to address this problem, but we're not super happy about what we have so far.

Given the time we have right now, the complexity of this problem, as well as having other priorities, we all agree it's best for us to spend more time investigating this issue and fully explore potential design solutions. In addition, we're hoping to get user feedback on this and incorporate that into our solution.

That said, we will keep investigating and exploring and hopefully have a more clear idea on which direction to go next week.

cc: @sjcox-rh @amysueg @rhuss @gashcrumb

[gashcrumb]

+1 sounds good to me!

[dongniwang]

Reference: #35

[dongniwang]

Reference: syndesisio/syndesis-ui#1000

[dongniwang]

Just including a note here based on @rhuss comment about Integration Name and Description. Need to think about:

• During the Create Integration workflow, when do we ask users to input Integration Name and Description
• Once an integration is a draft or has been published, where and how can users edit Integration Name and Description

[dongniwang]

Reference: syndesisio/syndesis-ui#1001

[dongniwang]

syndesisio/syndesis-ui#1056 (comment)

[dongniwang]

I have a few questions as I start re-working the integration details page:

Can different versions have different names?

• I think for both "Save as Draft" and "Publish" actions, users can change the integration name.
• If that's true, the Integration Name we show on the details page is the current published/running/active version's name?
• In this case, it means the draft integration has a name as well?

cc: @rhuss @gashcrumb @chirino @amysueg @seanforyou23 @sjcox-rh

[gashcrumb]

Well shoot that's a good question :-)

We don't currently prevent the user from changing the name, but what would be the runtime side-effect if the user does this? Do we rename the deployment config etc.?

[dongniwang]

Ok, here comes another question:
Do all the different versions of a given integration have the same start and finish connections? Can different versions have different start and finish connections?

[gashcrumb]

Do all the different versions of a given integration have the same start and finish connections? Can different versions have different start and finish connections?

It's possible to change the start or finish connection currently yes, so yes there's no guarantee currently that the integration history will have the same start/finish connections throughout.

[dongniwang]

@gashcrumb thanks! That's what I thought too....

@rhuss Can we talk about this tomorrow?

[rhuss]

@dongniwang Actually, I'd like to revive the idea of an IntegrationRevision (which actually is a concrete version of an integration definition (i.e. the connections + steps). They don't have individual names. An IntegrationRevision belongs to an Integration and somewhat inherits its name from it. So when you change the integration name, then its changed for all revisions implicitly.