How Better-learn works

1. 1

   Install the GitHub App on your organization

   Better-learn works through a GitHub App installed on the organization that will own the assignment repositories. Once it is installed, that organization shows up on your dashboard and you are its first teacher. A personal GitHub account cannot host generated repositories, so an organization is required. Creating one is free.

2. 2

   Create a classroom

   One classroom per course or batch. It holds the assignments and the roster of students who joined it.

3. 3

   Publish an assignment

   Two ways. Describe it and you get back starter code, a runnable test file, and the grading setup, reviewed by you before anything is created, then committed to a new private template repository. Or bring your own repo that you have already marked as a template. Either way you end up with a test command, a time limit, and an optional due date.

4. 4

   Invite your students

   Every classroom has an invite link. Share it, show the QR code, or email it to up to 50 addresses at once. Each person gets their own message, so nobody sees anyone else's address. Students who open it and sign in with GitHub are enrolled automatically.

5. 5

   Add a co-teacher, if you have one

   Invite a teacher on the dashboard creates a separate organization-wide link. Anyone who accepts it can publish assignments and see every student's work in that organization, so treat it differently from a class link. It expires sooner and allows fewer uses on purpose.

6. 6

   Watch the results arrive

   Every student push is graded automatically. The classroom roster shows the latest verdict and score per student, the assignment page shows the whole class at once, and you can export it as CSV. You never have to open GitHub to grade anything.

1. 1

   Open your teacher's invite link

   Sign in with GitHub. That is the whole sign-up. There is no separate password, and joining enrols you in that classroom.

2. 2

   Accept an assignment

   Accepting creates a private repository of your own, copied from the teacher's template. Nobody else in the class can see it. Clone it and work in it exactly as you would any other repo.

3. 3

   Push your work

   Every push is graded. No button to press, no file to submit. Your code runs in an isolated sandbox with the assignment's test command, and the exit code decides pass or fail.

4. 4

   Read the check on your commit

   The result comes back as a check run on GitHub, next to the commit that caused it. Open it for the full test output, including which tests failed and why. If your teacher enabled it, a short explanation of the failure is included.

5. 5

   Push again

   There is no penalty for a failed run. Fix it and push again. Assignments do have a daily limit on graded runs so nobody can burn the class's allowance in a loop, and your assignment page shows how many you have left today.

Common questions

1. What counts as passing?

   The test command's exit code, and nothing else. 0 is a pass. A score like 8/10 is read out of the test output when the runner reports one (jest, vitest, pytest, mocha, JUnit, cargo, go test), or from a line reading SCORE: 8/10.

2. What happens after the due date?

   By default late pushes are still graded and simply marked late. A teacher can instead close the assignment at the deadline, in which case a late push is recorded but not graded, and says so on the commit.

3. Who can see a student's code?

   The student and the teachers of that organization. Student repositories are private and are never shared between students.