Training (Katacoda) feedback

[gundalow]

Hi,

The Ansible Community is thinking about better ways to help onboard new contributors, as part of this, we are wondering about different ways to deliver documentation as training.

We are happy to announce some new interactive training scenarios to get people used to developing Collections.

Ansible Community Scenarios: https://www.katacoda.com/ansible-community/

Scenarios

• Scenario 1: Using ansible-test to identify a module that needs fixing

Feedback wanted ❤️

• Was it clear what you needed to do
• What did you learn
• Would do you think it could be good to cover in a future course
• Would any of the following be useful:
  • Check out a PR for local testing (how to find the git branch, and checkout)
  • Creating an empty collection and review structure (add a filter, test, module)
  • Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)

Source code

The source code for the scenarios is available in https://github.com/ansible-community/katacoda-scenarios Pull Requests welcome

[svpernova09]

Was it clear what you needed to do

Yes, my first time w/ Katacoda and it was very easy to use and follow.

What did you learn

How to fix a bug in a collection, Docker test runner is very handy/easy to use. Yikes Python 2.7!

Would do you think it could be good to cover in a future course

Step by step building tasks into roles into playbooks. Show a progression of small steps to larger objects without saying "Draw the rest of the owl" which seems to be common in Ansible training/learning resources. especially for Molecule/Testing.

Would any of the following be useful:
Check out a PR for local testing (how to find the git branch, and checkout)
Creating an empty collection and review structure (add a filter, test, module)
Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)

All of these would be useful!

[gundalow]

@svpernova09 Thank you for this feedback.

Could you possibly expand on:

Step by step building tasks into roles into playbooks. Show a progression of small steps to larger objects without saying "Draw the rest of the owl" which seems to be common in Ansible training/learning resources. especially for Molecule/Testing.

In an ideal world, how would you like this to be structured? Katacoda supports the concept of various labs linked together in a "Training Path", building on each other.

[kapil-git1087]

It was an awesome experience in the demo

[cpitre]

I liked the fact that there are step by step instructions along with the clickable command line interaction of the steps. It helps give a full 'picture' of the entire process.

What I learned: new tool for demoing instructions/process with Katacoda.

Migrating an existing ansible item (filter, module, etc.) scenario would be helpful.
At the moment this can be very useful for on boarding community members to being contributing members.

[gundalow]

Migrating an existing ansible item (filter, module, etc.)

@cpitre Thank you for the feedback, migrating from where?

[dpullman-emergent]

Was it clear what you needed to do

Yes. However, and I have the same thought for our workshops/demos: there was a nice bullet list of "this exercise will cover", but I wonder how to make a bit more explanation of what is covered? Maybe a tl;dr list and then a little more verbiage for those that are new to the steps?

What did you learn

Good intro to testing method in Ansible!

Would do you think it could be good to cover in a future course

Building a test in a simple collection as part of the scenario of building a simple collection.

(gundalow updated formatting)

[gundalow]

@dpullman-emergent Thank you for the feedback

there was a nice bullet list of "this exercise will cover", but I wonder how to make a bit more explanation of what is covered? Maybe a tl;dr list and then a little more verbiage for those that are new to the steps?

Just to check, do you mean on adding extra details about what will be covered on this page https://github.com/ansible-community/katacoda-scenarios/blob/master/fixing-a-bug/intro.md

[dpullman-emergent]

@gundalow Yes, that I think is the source of the content on the "Welcome" page of the scenario.

I've been wondering how to add more elaboration for those that might need or want it, but without making it cluttered. In a simple text page, it might be a tl;dr at the top, and then more verbiage just below it. In a more dynamic markup, maybe a link for each bullet that exposes more details?

Thanks!

[wolcen]

The scenario itself worked quite well.

Would love to understand better exactly how to write tests (unit and integration), but that I realize is a larger topic.

The exact way that molecule works/everything one should expect it to do for you is still a bit unclear to me personally, but I do admit to having to read some more here as well.

Note that I am thinking about molecule more from a role-developer's perspective than a module developer. From the module dev side, things seem a bit clearer. From the role-dev perspective, I've seen things as minimal as simply including the role, and nothing more.

[gundalow]

@wolcen Thank you for the feedback.

Would love to understand better exactly how to write tests (unit and integration), but that I realize is a larger topic.

Yup, I've love to have something on "How to write a test", will need help with how to structure that.
I wonder we could create an integration test based on what we already have for a module

Note that I am thinking about molecule more from a role-developer's perspective than a module developer. From the module dev side, things seem a bit clearer. From the role-dev perspective, I've seen things as minimal as simply including the role, and nothing more.

1. Are you suggesting you'd like to see a Molecule katacoda scenario specifically for role-developers?
2. What in particular isn't clear about Molecule for role-developers? What examples could we add?

FYI Molecule has it's own discussion area: https://github.com/ansible-community/molecule/discussions

[wolcen]

Thanks @gundalow .

In re: Molecule for role-developers, the demonstration during the event that @geerlingguy put on was exactly what I was looking for, so I'd use that as a basis.

[wolcen]

The formatting of the clickable link to edit the file did not stand out to me... I didn't even realize it was there (as I scanned for another clickable command) and so I just used vi :P

[gundalow]

@wolcen Ah, that's good feedback thank you.

Do you think this could be improved by adding some a line above saying you can click the link?

[wolcen]

@gundalow Hmm... I guess one could make it more obvious that way, or else in the text preceding it, mention to click the link below to edit it. Otherwise it just sits there as a random looking link...to me anyway.

Another point is that it IS made quite clear during the introduction, that clicking commands can be done to enter them for you. Perhaps it would be best to add an example of a file editing link here as well. This could demonstrate the functionality for opening the editor and maybe also mention using the 'X' for closing/saving the file?

[wawrzek]

Step 3

Now add the type for the append_privs parameter in the documentation for the by editing file plugins/modules/mysql_user.py.

It's not clear that you can just click to open the file.

I suggest:

Now add the type for the append_privs parameter in the documentation for the by editing file plugins/modules/mysql_user.py. The file can be open by clicking on the link below. Alternatily, open it with vim in the terminal window.

Also, I don't know how quickly move to line 1004 (in the editor, I know how do this in vim ;-).

[g1franc]

Was it clear what you needed to do: Yes
What did you learn: How to run sanity test on an Ansible community module
Would do you think it could be good to cover in a future course: Unit and integration test
Would any of the following be useful:

• Check out a PR for local testing (how to find the git branch, and checkout): No, already know how git behave but the setup of the local testing environment would be useful
• Creating an empty collection and review structure (add a filter, test, module): Yes
• Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.): Yes

[manueltarouca]

The lab was great, but IMO the click to run the commands might be a little overkill, for those who are experienced might be nice to have, but for those who are newcomers don't get the knowledge of what does the commands do.

[gundalow]

@manueltarouca Thank you for the feedback

For those that are newcomers, do you think before every clickable link we need to add more detail of the "what it's doing and why"?

[Caseraw]

Nice lab. Good job!

[jrglynn2]

Was it clear what you needed to do
Yes, very clear and easy

What did you learn
How to sanity test using docker, as well as fixing an issue with the test and re-running test

Would do you think it could be good to cover in a future course
Quite frankly, everything lol.
But specifically:
- the creation of a module from scratch would be great.
- anything AWS specific - or any cloud-specific Ansible training for that matter
- Ansible Tower

Would any of the following be useful:
Check out a PR for local testing (how to find the git branch, and checkout)
For me, not useful - there are a ton of GIT resources out there
Creating an empty collection and review structure (add a filter, test, module)
Yes, definitely
Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)
Yes, definitely

Thanks!

[prantikb]

Was it clear what you needed to do
Yes.

What did you learn
It was my first interaction with ansible-test. So far, I was used to using debug module for my unit testing. I would definitely explore this option. However, it would be nice to have some guidance on the best practices for testing ansible playbooks where large files (say installers) and a lot of shell / command modules are involved though each of them have their own changed_when / failed_when or other parameters to make them idempotent.

Would do you think it could be good to cover in a future course
In Step 4, I felt it was more mechanical following the instructions - may be because I am not used to looking at ansible module code in Python. It would have been nice to get some backgrounds on what to look for, basically how to map the error messages to the actual underlying python code.

Would any of the following be useful:
Check out a PR for local testing (how to find the git branch, and checkout) - Yes
Creating an empty collection and review structure (add a filter, test, module) - Yes
Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.) - Yes. An example session for absolute beginners for ansible testing would be really helpful.

Thanks!!! By the way, the katakoda lab option is excellent.

[gundalow]

@prantikb Thank you for the feedback.

In Step 4, I felt it was more mechanical following the instructions - may be because I am not used to looking at ansible module code in Python.

Just to clarify, do you mean Fix mysql_user.py step from https://github.com/ansible-community/katacoda-scenarios/blob/master/fixing-a-bug/step3.md

It would have been nice to get some backgrounds on what to look for, basically how to map the error messages to the actual underlying python code.

What exactly would you like to see here?

[prantikb]

@gundalow

Just to clarify, do you mean Fix mysql_user.py step from https://github.com/ansible-community/katacoda-scenarios/blob/master/fixing-a-bug/step3.md

Hi John, This is right. I was referring to Fix mysql_user.py step.

It would have been nice to get some backgrounds on what to look for, basically how to map the error messages to the actual underlying python code.

What exactly would you like to see here?

With reference to the below error,

the "Fix mysql_user.py" step says

I felt along with just the line number, if the section in the file is also mentioned, it might have helped to correlate the error message with the code easily. Basically, some pointers to "what to look for" and "why" in a broader sense.

[AdamMorris23]

Was it clear what you needed to do

Yes, mostly, although I didn't realise that you expected me to edit the file in the upper (editor) pane and not just use vi in the terminal. As a result I wasn't sure what I was expected to do with the X at first, and why I had to close the editor tab was not made clear.

What did you learn

How to run ansible-test, although without any real in-depth testing scenarios. How to resolve issues.

Would do you think it could be good to cover in a future course

I would like to learn how to write tests for ansible-test rather than just run pre-existing ones.

Would any of the following be useful:

• Check out a PR for local testing (how to find the git branch, and checkout)

I already know how to do this, so not especially

• Creating an empty collection and review structure (add a filter, test, module)

Yes.

• Writing tests (especially from scratch, e.g. how to prepare environment - "setup*" roles, etc)._

Yes.

[gundalow]

Yes, mostly, although I didn't realise that you expected me to edit the file in the upper (editor) pane

A few people have mentioned about the editor not been clear. We will see if we can improve that

How to run ansible-test, although without any real in-depth testing scenarios. How to resolve issues.

Do you think this scenario should have on ansible-test, or that should be a separate dedicated scenario?

I'm wondering if we have a new scenario where people checkout a branch that has many CI failures and people need to run ansible-test till passes.

[AdamMorris23]

A new scenario where you can checkout a branch and test and fix it would be great. I would love it if it started with more detailed instructions and then gradually got less "helpful" so that you have to apply previously learned knowledge yourself.

[Priyansh-jsk]

Hi, The Ansible Community
Was it clear what you needed to do = Yes, I clear all steps.
What did you learn = I learn how to make directory in ansible , creating a changelog fragment and much more.
Would do you think it could be good to cover in a future course = Yes , I this it could cover future course and want happy attend more upcoming events.
Would any of the following be useful = It is all useful for me , I learn a lot.
Check out a PR for local testing (how to find the git branch, and checkout) = first I fork the repo and edit it and make it pull request. and commit it ,than we done with PR.

Thank you so much !!
Ansible Team looking forward to join more events.

[Priyansh-jsk]

Creating an empty collection and review structure (add a filter, test, module)
Yes, definitely I will do.
Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)
Yes, definitely

[deecortes]

• Was it clear what you needed to do
  Yes.

• What did you learn
  Ansible testing using docker

• Would do you think it could be good to cover in a future course
  Yes

• Would any of the following be useful:

• Check out a PR for local testing (how to find the git branch, and checkout)
  Yes

• Creating an empty collection and review structure (add a filter, test, module)
  Yes

• Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)
  Yes

[sasidatta]

Easy tutorial and good lab setup.
I got the basic knowledge documentation source code.
Thank you for the workshop.

[saurabhgalav]

Was it clear what you needed to do

• Yes, It was very much clear.

What did you learn

• Using Docker, testing & fixing issues.

Would do you think it could be good to cover in a future course

• Yes, It would be good practice and good learning.

Would any of the following be useful:
Check out a PR for local testing (how to find the git branch, and checkout)
Yes.

Creating an empty collection and review structure (add a filter, test, module)
Yes.

Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)
Yes.

[vzhovtan]

Was it clear what you needed to do. ---  Yes
What did you learn.  ---   Some useful info about ansible testing
Would do you think it could be good to cover in a future course.   ---   More complex test cases
Would any of the following be useful:
    Check out a PR for local testing (how to find the git branch, and checkout). --- Definitely yes
    Creating an empty collection and review structure (add a filter, test, module).  ---   YES
    Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.).  ---   Double YES

[miwhalen]

I think the idea and implantation are fantastic.

The only constructive feedback I have is possibly add a bit more explanation. Dealing with new talent as frequently as I do, sometimes walking people through the steps is just not enough. A bit more detail into why (whether by links, mouse-overs, etc.) may help expand some understanding, and thus retention.

Again, great job, I can't wait to see more.

[gundalow]

@miwhalen Thank you for the feedback.

The only constructive feedback I have is possibly add a bit more explanation. Dealing with new talent as frequently as I do, sometimes walking people through the steps is just not enough.

How much detail do you think should be gone into, for example on https://github.com/ansible-community/katacoda-scenarios/blob/master/fixing-a-bug/step2.md what else should I add?

A bit more detail into why (whether by links, mouse-overs, etc.) may help expand some understanding, and thus retention.

Linking to existing documentation is a great idea, thank you.

[wawrzek]

Step 4

Maybe it's possible to create an empy file and allow to open it with editor, rather than run the cat command?

[gundalow]

Maybe it's possible to create an empy file and allow to open it with editor, rather than run the cat command?

Great idea, thank you.

[cynthia-rempel]

I really liked how the exercise walked the learner through checking out the module and making a fix. This would be really great as an introduction to this topic. I kind of was feeling like there should have been something telling the user to grep for the method call failing the test. I agree with the statements above more verbiage for later parts of the lesson would be very helpful.

[gundalow]

@cynthia-rempel Thank you for the feedback.

I kind of was feeling like there should have been something telling the user to grep for the method call failing the test. I

Could you please expand on what you are suggesting by this?

[aesyondu]

Was it clear what you needed to do
Very clear.

What did you learn
That ansible-test --docker pulls a lot of images

Would do you think it could be good to cover in a future course
...

Would any of the following be useful:

• Check out a PR for local testing (how to find the git branch, and checkout)
• Creating an empty collection and review structure (add a filter, test, module)
• Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)

[arnoxit]

Was it clear what you needed to do

Yes, easy to follow. The inline editor stumped me for a while about how to save, rather than just close the document.
The comment in the step helped but had a small typo: "Once you've added the line, click the x on the top of the file name to edit the editor and save mysql_user.py" ... should be "exit the editor". Although it actually appears to save as soon as you make a change in the editor without closing the file, as can be seen by the timestamp and size of the file in the shell window.

What did you learn

About katacoda

Would do you think it could be good to cover in a future course

Yes, the more training available the better

Would any of the following be useful:
Check out a PR for local testing (how to find the git branch, and checkout)
Creating an empty collection and review structure (add a filter, test, module)
Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)

All these would be useful

[bishgupp]

The Katacoda is a very good environment for learning and running demos.
it was very easy to start up the scenario and to enter and run code.
Directions were clear and easy to follow.

[mwtrigg]

• Was it clear what you needed to do

Instructions were very clear, detailed and thorough. I could see how some people may have missed the editor above, but all in all, that wasn't that distracting.

• What did you learn

-- about the ansible-test command
-- how easy it could be to make a quick fix to a module.
-- how easy it was to integrate docker into the process
-- Most importantly -- I LEARNED KATACODA EXISTS!!! -- This is a life changer.

• Would do you think it could be good to cover in a future course

This tool would be fantastic for basic intro-to-ansible content, not strictly contributor-type material. I feel very confident in this environment knowing that I'm not going to break anything.

• Check out a PR for local testing (how to find the git branch, and checkout)

Yes.

• Creating an empty collection and review structure (add a filter, test, module)

Yes.

• Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)

I may be looking to create modules from scratch, so writing tests from scratch would be very helpful. Testing is my weakest point.

[gundalow]

@mwtrigg Thank you for the feedback

-- Most importantly -- I LEARNED KATACODA EXISTS!!! -- This is a life changer.

Yup, This is the first time I've used it (or created any courses in it), I'm really impressed.

[J-F-Far]

Was it clear what you needed to do?
Yes, very clear.

What did you learn
How to run sanity tests using ansible-test within a docker container environment.

Would do you think it could be good to cover in a future course
How a user should add their own unit or integration tests, and adding a new collection.

Would any of the following be useful:
Check out a PR for local testing (how to find the git branch, and checkout)
There are plenty of Git resources out there in the wild. It is probably not a good use of effort to cover this one

Creating an empty collection and review structure (add a filter, test, module)
Yes.

Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)
Yes, I would like to see more thorough testing exercises in particular. As a Software Developer who uses Ansible on a day-to-day basis, but has yet to contribute to the project, anything that lowers the learning curve will mean that I am more likely to contribute to the project.

Thanks.

[Gauravtalreja1]

The very good lab covers many things for testing and fixing collections, Good job! 👍
Looking forward to many such labs to get started and to learn with the Ansible community!

Thank you!

[RobW3LGA]

Woo hoo! I did it! What do I win?

[gundalow]

For a chance to win swag please provide some detailed feedback (see the questions at the top of this page)

[RobW3LGA]

Well, fine :)

Was it clear what you needed to do: Supremely!
What did you learn: Appears to be the entire cycle of implementing Ansible, correcting code and uploading a PR.
Would do you think it could be good to cover in a future course: Module creation/edit fundamentals, playbook (YAML) troubleshooting and UNIT TESTING
Would any of the following be useful:
Check out a PR for local testing (how to find the git branch, and checkout): Yes but in an applied sense like the demo.
Creating an empty collection and review structure (add a filter, test, module): Interesting, a little more advanced but yes.
Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.): HA - DEFINITELY but you have to (somehow) make it compelling: Test writing has been likened to quitting smoking.

[wawrzek]

• Was it clear what you needed to do - Yes. No place to really get lost

• What did you learn - I'm rather power user, so there was not a lot of new knowledge, but it's good to have a practice with things you have learnt

• Would any of the following be useful:

  • Check out a PR for local testing (how to find the git branch, and checkout): No. However, it might be nice to have such lesson in another place
  • Creating an empty collection and review structure (add a filter, test, module): Yes. That might be a nice base of set of lessons
  • Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.): definitely. I enjoy the session we had before katacoda lesson, but it would be great to actually write something similar yourself.

• One quick addition - show how to limit the scope of the test to run just one Python distribution to speed it up. The order could be - run a test with a bug; fix it; confirm that the problem is address with just one distribution, rerun the whole suite

[clsmith70]

Was it clear what you needed to do

• Yes, the instructions were easy to follow. In some places I had to read it twice to fill in missing words.

What did you learn

• I learned how to test code. As a new user/admin of Ansible Tower, this will be very helpful.

Would do you think it could be good to cover in a future course

• The sky's the limit

Would any of the following be useful:

• Check out a PR for local testing (how to find the git branch, and checkout)
• Creating an empty collection and review structure (add a filter, test, module)
• Writing tests (especially from scratch, e.g. how to prepare environment - "setup_*" roles, etc.)

• I think these would all be useful, especially for anyone new to one or more of the processes listed