Hackfest guidelines for outreach WG

[gregdek]

"How to run a hackfest" is a thing we could use.

Hoping for some input from @mscherer here when we're ready for it, since he's run hackfests and has good feedback on what worked well and what didn't.

[mscherer]

I did co-organize only one hackfest with @pilou- , helped for a few others ones on explaining ansible, and he did I think most of the work, so I will let him complete. But from what we learned on the one at 21/22 september for pycon.fr, I would stress the following:

• not everybody will have read the requirements and/or follow them. If you ask to people to have ansible installed first, some will not. If you ask to get a checkout, some will not. So at least 1 member of the org team should take care and deal with that. Sometime, that's people starting from zero, so needing some help on git, github, etc.

• people will come with weird stuff. We had someone coming with Arch linux, and I never used it. Turn out that the python == python3 change of arch linux did made our life more difficult. Someone wanted to use pip + a virtualenv wrapper, but python-crypto couldn't install due to deps issues. So ideally, in a perfect team, you will need a sysadmin and/or a linux packager to take care of fixing this kind of stuff.

• if there is a release the week before, make sure to test the process of setting it from scratch. The python crypto requirements of 2.4 did surprised us a bit, nothing blocking, but it wouldn't have hurt for us to look at the bugs before.

• make sure to have someone who master git and be ready to explain to people who do not master it, or even never used it. It help to practice on student to see what would cause them trouble. It also help to keep in mind that $EDITOR point to vim by default, and not everybody is vim-fluent either.

• if you explain something before the sprint, be sure to explain it again for people coming later. We got people late, and no reason to refuse, but this mean you have to get one organizer to take care of the person.

• make sure people can contact you after. I didn't do it (except in later talk), but since @pilou- did for him, people were able to contact him. Business card can help, discussing on a shared chat room can help, etc. The goal is also to grow community, so people should know where to find you if they have questions.

• we had no issue with anyone not speaking english well enough, but that's the kind of stuff that could happen, so plan to be here to help on PR and bug redaction/translation, and do not hesitate to advertise it.

So having 2 persons is a minimum, 3 usually do not hurt. One should be dedicated on fixing random stuff that requires time to let the other focus on helping others, explaining to the group, etc. Do not assume anything regarding what will happen, since people will come with their laptop.

We did decide to focus on modules and tests, for several reasons:

• they are usually self contained, which make them easier to understand
• they are easier to test and fix, either with hacking/test-module or hacking/env-setup
• there is likely lots of low hanging fruits

So this permit to get quickly a first contribution to ansible, thus motivating people.

Touching to the core of ansible requires to run the test suite, and this is more time consuming and more complex. Doing it cleanly requires to have docker or a VM, and both requires a working network, which is far from being garanteed during events. And besides that, this might be a burden for a newcomer.

Using ansible ad-hoc command and a local checkout has a much lower friction IMHO, since it just requires people to use ansible as usual.

On top of that, modules permit to quickly see if people are working on the same stuff or not, since they just need to tell which module they look at. Using sivel website (https://ansible.sivel.net/byfile.html) permit to find a list of PR to review and test, which is also a way for people to help.

We plan to do it again, but in Paris this time. To mitigate the issue of people not prepared, and to adapt to the schedule of the proposed room, we want to do it with 2 separate date. One to present (and prepare for people who didn't prepare), and a second one to focus on coding, with a few day between so people can search by themself. I will report how it work if we can make it.

[mscherer]

So thinking a bit more, I wonder if a cheat sheet could help (especially if translated), something to be printed and distributed so people know they can refer to it for the first contribution, and take it home.
It would have the following:

• example for the hacking/env-setup and test-module command, with quick documentaion
• giving a rough idea on where to find modules in the git repo and other smaller piece of code (plugins)
• a quick reminder on git main command (and workflow to submit a patch)
• contact information for organizers
• get in touch with community
• what/how to interact with the bot
• how to build doc, write doc
• how to write test, run tests (might become complicated fast however)

[gregdek]

Thanks for the input @mscherer. Trying to figure out what the minimum viable hackfest guide looks like. I think the "how to make your first Ansible contribution" would be a great thing to call out specifically, and the goal of most hackfests is to get people making those first contributions.

Seems like the minimum elements of a hackfest are:

• a room
• a few people who want to hack
• a mentor present who can:
  • point to issues that might be achievable
  • give realtime feedback
  • ideally, perform patch reviews in real time

Basically, it should be an accelerated version of what the whole process would be like.

Does that seem reasonable?

[Ian-T-Price]

I've three decades of IT support under my belt and used to learning new systems from poor docs. I'm still wading through the various links about how to contribute to Ansible which are scattered throughout the docs. I've still yet to contribute after two weeks.

The cheat sheet should probably be part of 'Refactor Ansible Core Documentation Into Modular Guides' ansible/proposals#79 but it is very much needed if you want to increase the level of contributions

[gregdek]

Thanks for this, @Ian-T-Price -- would love the painful view from your perspective. We've grown very organically. Got some time to walk us through your process?

[gundalow]

@Ian-T-Price See also #169 for community docs refactoring

[mcgonagle]

@gregdek Thanks for creating this thread. @gundalow thanks for sharing this with me. We (F5 Networks) are going to have a fun hackfest at our user conference in August. The 4 hour hackathon will be to network and do something "cool" with Ansible and Raspberry PIs. We are going to be getting local university's (Boston the location, is a College town) involved and the event is supposed to be a fun, social event. We will certainly take the recommendations of this thread and try to apply them.

@mscherer is there a need for sponsorship? If so, I'd like to offer F5's sponsorship of the next HackFest being planned for Paris. Please do reach out.

[mscherer]

@mcgonagle For Paris, we do not have yet a idea of how much people would be coming. I am out fo OSS EU for now, so the organisation on my side is a bit on hold until I am back. I am gonna ping the 2 others to see if we may need or use the sponsorship, but last time, I just paid for pastry so 10€ of spending is unlikely to be worth the effort for doing sponsorship.

But thanks for the offer anyway

[itdependsnetworks]

IMHO, it is probably cheaper to host an environment that is pre-staged then get everyone to install all of their dependencies, and the cost of additional engineer's time to support.

[gundalow]

@mscherer @pilou- recently ran a hackathon in France, would be good to capture lesson learnt in here. Happy to jump on a call with you two if that's easier

[gundalow]

Also after Austin include details from NGINX hackathon

[mscherer]

@pilou- wrote a report, but in french, let me translate it:

==============
We did from 10h to 20h, during the weekend.

Number of participants: 3 (planned, 4, one couldn't come). First morning was around showing the contribution workflow, useful tools and tips (env-setup, test-module, etc)

People questions:

• how to get PR accepted, how to get it done faster
• how to debug a module

We did:
5 previous PR review
9 PR created and reviewed during the workshop

6 have been accepted at the time the report was written

List on https://pad.picasoft.net/p/Ansible-Scaleway

We also did discuss at restarting the ansible meetup, and get a stronger local community.

============

In term of lessons, I would say that communication was ok (3 months before, then restart again 2 weeks before) on the main french websites. We did avoid the holidays on purpose, but not enough. I think we did face a roadblock with the local Ansible meetup to be dormant, and use not able to send messages, but we figured after the event we could have fixed that.

The number of people who came were kinda the same as we got in December (aka 3 to 4) when doing a event during the week, so the time didn't seems to change much the attendance. Having a full day event was important, since we had plenty of time to discuss. And while @pilou- did prepare easy PR/bugs, people came with their own stuff anyway since we did got existing contributors.

Being 4 with 2 contributors did permit to have lively discussions and good training around edge cases and faster review. However since we did discuss it around the table rather than using github, I think some of what was said was lost, especially around a few non trivial choices that were discussed, which is not really future proof.

[pilou-]

An available (in person or online) core team member is definitely recommended.
As before, we did decide to focus on modules.
2.7 dev guide is definitely better than it was one year ago.
Advise people to become maintainer and to create team :)
We failed to convince participants to add new tests (unit tests were the only option) :-/

[pilou-]

@mscherer and I recently ran another hackathon in France. Again, we did decide to focus on modules.

• Number of participants: ~13. First morning was around showing Ansible (ansible command, an example playbook, controller vs managed, env-setup). Useful tools and tips (JSON stdin/stdout, test-module, ANSIBLE_KEEP_REMOTE_FILES, explode, etc) and community informations (working groups, meetings, contribution workflow) were discussed throughout the hackathon.
• People questions:
  • how to debug a module
  • why XXX PR isn't merged
  • how to use Ansible with Docker

We did:

• #29687 module django_manage: analyze bug report, add a comment explaining why the issue can be closed and ping a maintainer. Issue still not closed.
• #30592 close bug report, issue was fixed in 2.4
• #40900 module npm: add no_save option, tests included, rebase and minor update required
• #41904 module mysql_db: PR tested and reviewed by one participant, comment added. PR still not merged yet, rebase required.
• #43011 module ini_file: issue not reproduced, comment added
• #46478 module haproxy: bugfix merged
• #46490 modules service and systemd: changes required
• #46515 module haproxy: improve drain mode, waiting review from maintainers. New PR: #59156, not merged, waiting for reviewers.
• #46525 module grafana_dashboard: bugfix, 1 approval, waiting for another. New PR: #59157, not merged, waiting for reviewers.
• #46526 module mongodb_user: change required
• #46527 module docker_volume: tests provided, change required
• #46545 analyze issue (su and pty with connection local), comments added. Issue closed as a duplicate of #38696.
• #46544 module django_manage: idempotence bugfix, 2 namespace maintainers notified, reviewed, change required.
• #46547 docker connection plugin: add docker_cwd parameter, tests provided, change required
• #46581 module azure_rm_virtualmachine: add availability_zone parameter, closed but not merged.

In term of lessons:

• there are more participants when the hackathon takes place during a bigger event (here it was PyConFR, there was several hackatons).
• some participants came because we emphasized in hackathon description that Ansible/Python beginners were welcome
• required demo: clone GitHub repository, create a virtualenv, source env-setup, wrote a simple playbook with a simple module, how to debug a module (local, remote)
• some people came with a list of issues/PR but a list of easy fixes was useful (this list needs to be created before the event and related issues should be about various modules)

[webknjaz]

required demo: clone GitHub repository, create a virtualenv, source env-setup, wrote a simple playbook with a simple module, how to debug a module (local, remote)

probably needs an asciinema recording..