Github5561

#5561. When a .grc file behaves differently due to being opened on different GRC version

This work is related to Github Issue 5561.

1. Do research with community to understand what they do when this happens currently. I've put together a short survey to ask users for their experience of this situation, what behaviour was caused, how they dealt with it. Based on the results of that research we create some notifications with advice on how to deal with it. 2. Analysis of the survey quantitative data being done using a collaborative online whiteboard called Miro. You're welcome to leave comments on the Miro board. 3. Write the draft support documentation. Send it to the UX group and to the mailing list for contributions or comments. 4. Do UX design for notification.

Research write-up

Summary

We carried out research with GR users to learn how they dealt with issues arising from the following use-cases:

1. opening a .grc file created with an older version of GNU Radio, in a newer version. 2. opening a .grc file created with a newer version of GNU Radio, in an older version.

We wanted to learn about the following:

1. if they had issues with either of these scenarios happened to them, and if so asked them to describe the situation 2. the most common causes 3. the troubleshooting routes they took 4. how they fixed the issue

This is all obvious!

While this might be obvious to those of you who are expert GR users, it won't be obvious to most people. Also, gathering evidence allows us to make better decisions.

Objective

The objective was to use what we learned to write documentation that supported GNU Radio users of all levels of experience.

Findings

1. This is a common issue!

- All participants experienced issues with both scenarios

2. The documentation needs to be readable by users of different levels of experience

- Users with differing years experience (from 1 to 10 years) all experience these issues - Users with differing years experience used the same/similar troubleshooting routes and fixes

3. Documentation should provide sign-posting to the community when users can't fix the issue

- Sometimes it wasn't possible to fix the issue. If none of the suggested fixes work, they should be directed to the community for possible help

3. In some cases issues had several solutions

- In terms of troubleshooting an issue, this is an obvious statement to make, but it's useful when working out how to write/structure documentation for users.

4. It wasn't possible to identify clear issue -> troubleshooting -> fix route patterns

- This means the best we can do is provide advice that might possibly duplicative advice, i.e. some causes might have similar troubleshooting paths, fixes.

Causes

Issues were caused by the following: (ranked by how common)

1. Missing blocks/modules - Blocks not being installed - Out Of Tree Modules/Extensions missing/not installed - Block locations changing/being reorganised between versions - Blocks being removed e.g. wxwidgets

2. Block/module incompatibilities caused by running multiple different versions of GRC on the same machine

3. Incompatibilities due to changes in block formats over different GRC versions

4. Appropriate alternative blocks not being available in older GRC versions

5. Blocks being renamed over new/older GRC versions

6. Block parameter changes over versions

7. (newer) Blocks not backward compatible

8. Undetermined bugs/issues

Fix/solutions

Fixes and solutions outlined by users were (ranked by how common)

1. Rewrite/redraw the flowgraph

2. change the incorrect block parameter

3. convert flowgraph

4. replace block(s) with another

5. port or rewrite block(s)

6. recompile modules

Troubleshooting routes

Trouble-shooting routes were mapped as followed:

Special:Upload

There were not clear routes, but some definite paths existed.

Troubleshooting routes mentioned by users were: (ranked by how common)

1. Inspecting the .grc file or block code

2. Reading error messages then doing an Internet search

3. Reading error messages then installing missing blocks/OOT module

4. Reading documentation

5. Debugging code (specified Python)

6. Asking GR community for support

7. Using UI error notifications ("problems are shown in red")