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

[syndesis-bot]

@gashcrumb	2017-09-15	UX Design, UX Research

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...

[syndesis-bot]

@dongniwang	2017-09-15

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?

[syndesis-bot]

@gashcrumb	2017-09-15

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.

[syndesis-bot]

@dongniwang	2017-09-15

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.

[syndesis-bot]

@gashcrumb	2017-09-15

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?

[syndesis-bot]

@rhuss	2017-09-18

@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 ?

[syndesis-bot]

@dongniwang	2017-09-18

@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

[syndesis-bot]

@iocanel	2017-09-19

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.

[syndesis-bot]

@gashcrumb	2017-09-19

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.

[syndesis-bot]

@dongniwang	2017-09-19

@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.
  

[syndesis-bot]

@gashcrumb	2017-09-19

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.

[syndesis-bot]

@dongniwang	2017-09-19

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.

[syndesis-bot]

@dongniwang	2017-09-19

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.

[syndesis-bot]

@gashcrumb	2017-09-19

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 :-)

[syndesis-bot]

@sjcox-rh	2017-09-19

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?

[syndesis-bot]

@dongniwang	2017-09-20

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 ;-)

[syndesis-bot]

@dongniwang	2017-09-20

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

[syndesis-bot]

@gashcrumb	2017-09-20

+1 sounds good to me!

[syndesis-bot]

@dongniwang	2017-09-20

Reference: #314

[syndesis-bot]

@dongniwang	2017-09-21

Reference: syndesisio/syndesis-ui#1000

[syndesis-bot]

@dongniwang	2017-09-21

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

[syndesis-bot]

@dongniwang	2017-09-21

Reference: #231

[syndesis-bot]

@dongniwang	2017-10-06

syndesisio/syndesis-ui#1056 (comment)

[syndesis-bot]

@dongniwang	2017-11-09

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

[syndesis-bot]

@gashcrumb	2017-11-09

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.?

[syndesis-bot]

@dongniwang	2017-11-13

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?

[syndesis-bot]

@gashcrumb	2017-11-13

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.

[syndesis-bot]

@dongniwang	2017-11-13

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

@rhuss Can we talk about this tomorrow?

[syndesis-bot]

@rhuss	2017-11-14

@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.

[amysueg]

@dongniwang @rhuss Since #359 was merged, can we close this issue?

[dongniwang]

Closing this issue. Latest design please see PRs below.
#372
#414

[gashcrumb]

Absolutely...