Make slides for October 2024 course

[alessandrofelder]

Goal

Update the slides for this year's courses

Constraints

We only have 1.5 hours, so we need to reduce the amount of content, and maybe move some of it to homework.

[alessandrofelder]

Suggested implementation plan:

• start with packaging, and demo the cookiecutter template, so they learn how to install local versions of their package, and structure the code nicely
• have a discussion about what makes code good
• demo a contribution to real-life project, showing the whole lifecycle: select issue -> make a fork -> clone locally -> make changes locally -> write a test for the local changes -> push -> make a Pull Request.

I am suggesting this because:

• This feels a lot more doable for the time
• This feels more useful for the students

The downside:

• it's less hands-on (there's still a fair bit of mentimeter discussion triggers)
• requires a lot of changes to the material (but would make it simpler... unless we reformat the exercises as homework)

What do you think @lauraporta ?

[lauraporta]

Thanks @alessandrofelder for writing these notes. One hour and a half is not much to go through this material. I see that the suggested implementation goes through:

1. how can I work best with my own custom software
2. how can I collaborate to other open source projects

These two might be for an audience with different skillsets, as point 2 expects people to already be able to follow good software practices (at least that's how I see it). Also, by briefly introducing the files in the cookiecutter, I am scared that we are trying to cover too much in a short time.

I advocate to focus only on point 1 and expand on what we covered last time either by talking about tests and/or writing documentation. I am saying this because the cookiecutter creates templates for many objects that are cryptic to a new user and the course could feel more complete if we end up filling in the folders tests/ and docs/. Do you think that the coding time will slow down the course a lot?

I can see that the contribution to a real life project adds a lot of value... Maybe we can do a short non-interactive demo as you suggested.

It will be more hands on and will retain different sections of the material of last year... What do you think?

[alessandrofelder]

Yea, I think that's fair... I am worried that just showing: "Oh look in this folder, you can write some tests for your software" is not useful either, unless we also talk about what to test, how to test, etc...

Do you think that the coding time will slow down the course a lot?

Not sure. Depends how energetic the students are: it is day four of the computational course, 4pm-5:30pm and they will just have absorbed the confusing interface of git, possibly for the first time. So it may all be a bit much?

[lauraporta]

Please remind me... are they being introduced to git by Steve just before? One option is to translate what they learnt with git to the GitHub interface. Although that's not much... What if instead of introducing directly the tools we do a guided open discussion? We can pose problems and talk though together on how frequent issues can be solved in the best way, in order to make the necessities of certain tools self evident and possibly trigger their own self-learn journey. Is this an utopia?

[alessandrofelder]

are they being introduced to git by Steve just before?

yes, git and Github (according to Steve's slides from last year), so we can build on that. schedule and link to slides from last year are online

[alessandrofelder]

we do a guided open discussion?

It's an option. Again, I am a bit wary of

• creating extra work for ourselves
• overwhelming people with too many things at once, late on Thursday

How we strike this balance is the question we'd want to answer in this issue, I think.

[alessandrofelder]

I think we ~have a choice between

• a very high-level intro to all good practice concepts (packaging, issue tracking+PRs, testing, docs), so at least they've heard about them and have a starting point for self-learning - but make it clear we don't expect them to know more than "these things exist" after the course
• go deep into e.g. packaging and code organisation, and demo why it's useful in a hands-on way: e.g. you can pip install -e .[dev] and then import your functions from elsewhere...

[lauraporta]

I am persuaded, ok!

[alessandrofelder]

Laura suggests, as part of "go deep into e.g. packaging and code organisation" to describe it as a journey of growth, of the package.

1. you have your analysis script, and you notice some repetition -> you make something a function
2. you get a new project, and notice that that want to re-use that function in a different folder -> you structure as a package, and pip install -e .[dev]
3. Your friends want to use it too -> they clone your repo and also pip install -e .[dev] (and contribute)
4. The whole world wants to use it -> you publish your package on PyPI

(depending on time, just mention these things as part of a final discussion)

5. Lots of research depends on your function, and you start getting a lot of questions about it -> you start documenting it
6. People start submitting bug reports, and you are constantly changing your code: how do you make sure the bugs don't appear again? -> you write some tests

[alessandrofelder]

Plan for slides we discussed (please correct/complete @lauraporta )

• flip slides, to start with packaging
• move links to exercise to the end (as supplementary material that students can go through in their own time, and we commit to reviewing PRs for the next two weeks)

[adamltyson]

The journey/story idea is very nice. It might be good to also frame testing around reproducibility, catching errors before publication etc (some people may not care about external bug reports).