Fixme.jl – A Beginner Friendly Platform for Making Your Own Package

Package repo

Background

During the JuliaCON diversity dinner there was the idea to lower the barrier-to-entry for contributing to Julia packages. Our breakout group (focused on mentees) identified that imposter syndrome and self-consciousness about code was the one of the big reasons why people don't contribute to their favorite packages. We'd like to help these people by allowing them to implement a PR in a low-stakes environment, where they could get some feedback and learn about the development process from a mentor. Enter: the permanently broken package.

Description

Fixme.jl is a package containing a number of undesirabilities in the form of bugs, unoptimized code, lack of documentation and CI. The mentor can make a fork of this package and act as package maintainer, while mentees will learn about Julia, package development and community conduct by fixing these undesirabilities through the proper channel. The intent is to have this be as close to the real package development experience as possible. After completion, mentors can delete/revert their fork and create it anew to teach other mentees.

Target Audience for This Tool

The target mentee audience for this project is those who:

• Have familiarity with Julia scripting
  • Know basic Julia Syntax
  • How to use the Julia REPL
    • Including the different modes
  • Some awareness of git (but not required)
• Don't know how package development should work
  • Revise.jl workflow
  • Forking a package
  • Running test suites
  • Etc.
• Want to get involved in contributing
  • Also includes wanting to submit fixes for packages

Learning outcomes

For a mentee, they will learn how to:

• Identify an error (a bug) in a package

• What to do about filing an issue

  • Where to report an issue
  • What makes a good issue

• Develop a package

  • Using packages in a dev environment

• Create a PR against their repo

• Learn what tests are

  • How to create a test suite
  • Write tests
  • Run a test suite locally
  • How to debug tests

• Basics of improving "bad" functions

  • Using global environments alongside development environments
  • Why are globals bad

• "Good" Coding Practices

  • Documenting code.
  • Etc.

• Basics of GitHub Actions

  • What is a CI?
  • What is CD?
  • How to deploy documentation?
  • How to run a test suite

• Community Code of Conduct

  • How to formulate issues in a civil, constructive manner

Tasks

What Needs To Be Done

• A low-effort low-stakes environment. Make the package easy to understand for any background (e.g. a sorting package or the like). Make it so that most issues can be fixed (and have their fixes checked) in a very reasonable amount of time.

• Make it as close to the real thing as possible: provide some instructions, or list some issues in the README, but have the mentees actually file a Github issue, make a PR, have the code review stage, merge into main…

• Make it modular, not everybody is interested in/knowledgeable about CI, or some other topics so make them optional.

Specifics

• Create repo with PkgTemplates.jl
  • Enable GitHub
• Put a warning in the main module against using this in production code
• Initialize README
• For every mentee assignment (see below), make a separate branch (referred to as assignment here) and do
  • Come up with a broken example for a simple application of choice (sorting, binary search…)
  • Make a branch trial starting at your assignment branch so you can test whether you came up with a good assignment.
  • Do the assignment yourself. For the purpose of test-running what you came up with, the trial branch can be considered main, so you should make a branch myfix and merge that into trial after you're done.
  • Preferably have somebody else (or multiple others) do the assignment. Review together
  • Delete trial and myfix (if not done so already)
  • Updates to the assignment should be commited to assignment
  • Iterate
  • When satisfied with assignment, update the README with instructions on the assignment (for both mentors and mentees)
• Create an issue template
• Look at how CI can make the mentor's job easier
• Get this project promoted on the Julia socials @TODO

Mentee assignments

Fix an Undocumented but Very Obvious Corectness Bug

(Steps don't need to be exactly in order here)

• Mentee opens an issue
• Mentee forks repo, creates a new git branch
• Mentee implements a failing test, commits failing test
• Mentee fixes test, commits fix
• Mentee files a PR
• Mentee gets a code review from mentor
• Mentee gets contributor badge/adds themselves to the all-contributors file (?)
• Mentee merges once approved

Accelerate a Slow Function

Have the mentee accelerate a slow function. The cause of this function being slow can be allocations, globals, type instability, preferably a mix of them

• Mentor opens an issue, pings the mentee and asks for help accelerating this function
• Mentee and mentor set up a benchmark for function f0
• Mentee implements f1: a more efficient implementation of f0
• Mentee tests correctness and benchmarks f1
• Mentee files PR to implement f1
• Mentor gives feedback, ask mentee to demonstrate speed gains in the PR
• Iterate for f2… to possibly fix multiple speed issues
• If mentor is satisfied with progress, merge

Create Documentation

I'm not quite sure how some of these steps should be tackled as an assignment. In my experience it's the PR reviewer who usually asks for more documentation so I'm putting this on the mentor but I'm open to other workflows. Most essential is having people get familiar with function/struct documentation strings and Documenter.jl.

• Mentee opens an issue about lack of documentation
• Mentee writes documentation string for a function
• Mentee makes PR
• Mentor asks mentee to add the function to the Documenter website (basic Documenter setup is provided)
• Mentor asks mentee to make an example/tutorial for using this function.
• Mentor provides review and feedback on example/tutorial. (Teaching people how to write quality tutorials takes time but it's super important!)
• PR is merged once mentor is satisfied

Fix CI Problems

• @TODO