So you’re a tutor for a course that’s using lucy. Your convenor must have
excellent taste.
Setup#
See the Python installation instructions. You’ll only need to do this once at the start of semester.
Moderation#
You may be asked to mark a moderation set of assignments before assignment marking begins so that all tutors can calibrate their expectations with the course convenor.
The process is documented here. Moderation marking works a bit differently to regular marking because all the tutors are marking a small number of assignments.
Assignment Marking#
Your convenor may have set marking up so that you mark in the GitLab web UI
instead. If so, you don’t need lucy at all: they’ll send you links to the
marking forks you’ve been allocated, and you edit the marking file (e.g. marking.md, and pam.md
if needed) in each one with the GitLab web editor, committing as you go. The
convenor publishes a marking report listing your allocated students with a
link and a pass/fail check for each, so you can see what’s left to do.
Otherwise, the main marking workflow for Lucy assignments is
-
poetry run ./lucy.py clone <assignment_name> <-_ target>to clone the target student repos (i.e. their assignment submissions) to your machine -
go through each submission repo and add your feedback and a mark to the marking file(s) (e.g.
marking.md), committing & pushing as you go -
poetry run ./lucy.py push <assignment_name> <-_ target>to push the marks & feedback up to the marking GitLab repos (you can do this as many times as you like) -
poetry run ./lucy.py pull <assignment_name> <-_ target>to pull the latest commits from the marking GitLab repos (this won’t be necessary if you’re marking alone, on a single machine, but will be useful if someone else is also pushing commits to the marking repos for your group) -
poetry run ./lucy.py check <assignment_name> <-_ target>to check that everything’s hunky-dory for that group—when you’re done lucy will say “looks good to me” (lgtm)
Targets#
Most commands that act on student repos take an assignment name and then a
target flag saying which students to act on. With no target flag, they act
on every student (--group all).
There are 3 target flags:
--group or -G: specify a lab group to run the command on, or all for every student
--tutor or -T: specify a tutor name to run the command on where the allocations for that assignment for that tutor has been filled out
--uid or -U: specify a uid to run the command on (for use as just a single student)
Worked example#
So this is what for example clone will look like:
poetry run ./lucy.py clone ass1
clones all ass1 repos
poetry run ./lucy.py clone ass1 -G mon3pm
clones all ass1 repos by students registered to mon3pm
poetry run ./lucy.py clone ass1 -T Brent
clones all ass1 repos assigned to Brent in the ass1 allocations file
poetry run ./lucy.py clone ass1 -U u1234567
clones the ass1 repo for only the student with the uid u1234567
These flags are available for most commands, if unsure check with poetry run ./lucy.py COMMAND --help.
Data integrity#
All student submissions are cloned to your local machine, and are stored in the path:
submissions/<assignment_name>/<group_name>/<uid>
If you don’t have any “dirty” repos in submissions/ then you can safely delete
the submissions/ folder (you can just re-clone all the repos to re-create it).
However, if you’re in the middle of marking and have un-pushed changes in
any of those submission repos then they’d be lost if you delete the
submissions/ folder.
Other useful commands#
status#
To quickly see the git status of all your cloned submission repos at once:
poetry run ./lucy.py status <assignment_name> (--group <labname> | --tutor <name> | --uid <uid>)
This runs git status in each repo and prints the output. Useful for spotting repos with
uncommitted changes before you push.
update-token#
Lucy reads your GitLab token from data/secrets.yml every time it runs git, and
never stores it in your cloned repos, so if your token expires or changes you only
need to update data/secrets.yml.
Repos cloned with an older version of lucy still have the token written into their
remote URLs (in plaintext, in .git/config). This command resets those remotes to
plain URLs, without re-cloning:
poetry run ./lucy.py update-token <assignment_name> (--group <labname> | --tutor <name> | --uid <uid>)
list-students#
To see who is in a particular lab group:
poetry run ./lucy.py list-students --group <labname> --format <format>
Available formats: name, uid, email, md (default), ed, edlabs. Omit --group
to list all students. The --format=email option is useful for contacting your group
directly — but make sure you BCC to avoid leaking addresses.
Git hygiene#
We (the tutors) are all going to be working together on this shared repository, pulling & pushing many times over the semester. So let’s establish some conventions about how we’ll manage the git stuff.
Be careful about what you git add#
With small repos where you’re the only developer, it’s really tempting to just
do git add . or even git commit -am "did some things". However, this is
probably a habit which is worth getting out of—it can easily lead to
accidentally committing files you didn’t mean to (e.g. Desktop.ini,
.DS_Store).
Here’s my advice: before you commit, look at git status to see what’s up.
Then, add specific files to the commit with git add <filename>. Sometimes
adding a whole folder is ok if you’re certain that you want to commit all the
changes in there. Then, finalise the commit and write a decent commit
message.
rebase all the things#
Wherever possible, rebase your local branch to origin/master before you
push. This means that we won’t have lots of merge commits in the history, that
reverts will work much more easily, and the commit history will make more sense
(and
other
reasons). I
use git blame a lot to solve problems in big git repos, and if there are lots
of unnecessary merge commits then I can’t do that and I lose my git superpowers.
This should be really easy in most cases (i.e. no conflicts), since you’re all working on different files (except for when you’re working on a report with your co-tutor for the same group).
The main piece of advice I’d give is to use git pull --rebase instead of git
pull. You might want to set git pull to rebase by default, at least for this
repo. You can do this with
git config pull.rebase true
You can even add the --global flag if you want to change your pulling
behaviours across all your repos. But that’s up to you.
Line endings#
Life is messy. Different OSes use different line endings. C’est la vie.
However, we can stop this mess causing us git troubles by making sure that we
handle line endings properly in
git.
In particular, we never want to introduce a commit which just changes the line
endings, which can happen sometimes if your git configuration is borked. That
leaves big, hairy commit which touches every line of every file for no reason,
which causes problems down the line (e.g. making git blame less useful). That
GitHub help article can help you make sure you don’t do that.
No Gitshaming#
I (Ben) don’t expect everyone to be a git ninja to be a tutor in this course, I (and the other tutors) are here to help you out if you get stuck with any of this stuff. This goes for the way we deal with one another as well—we all make mistakes (even me!) and if that happens we’ll just fix them. No “your git-fu is bad and you should feel bad” comments.