How to enter the poetry competition

Git

Git is the modern standard for storing, working with and collaborating on code. It is used ubiquitiously in software engineering and ARTIQ relies on it heavily. It allows you to:

  • Store a history of snapshots of your code at moments in time (commits)
  • Refer to specific versions of your code unambigously using hashes of commits
  • Work with other people collaboratively by merging your changes into existing code
  • Use tools like GitLab to discuss changes before they are made and automatically perform actions on code (such as creating this PDF document, running a set of tests to make sure your code still works, or rebuilding an ARTIQ bitstream)

In AION, we use git to store all our collaborative projects in the AION group on GitLab: https://gitlab.com/aion-physics. You should already be a member of this group. If you are not, ask Charles to add you now.

If you're not part of AION, you will still find mastery of git critical for your ARTIQ work and other software projects.

Putting some time into learning Git will pay you back at a very good exchange rate when you later save yourself from lost or mangled code, track down the change which caused a strange bug to appear, need to replicate a result for a thesis that was produced with code from months (or years) ago, etc.

To learn Git, I suggest the great little tutorial at https://learngitbranching.js.org/. For the ARTIQ course, you should know everything you need to know if you do:

  • Lessons 1-4 in "Introduction Sequence"
  • Lessons 1-4 in "Ramping Up"
  • Lessons 1-8 in "Push & Pull -- Git Remotes!" (The master branch of this poetry competition is indeed locked, as described in level 8)

To enter the poetry competition (and join the ARTIQ course), complete the list of challenges below:

Exercises

  1. Do the exercises on https://learngitbranching.js.org/ or learn git commands your own way.

  2. Make an account on GitLab if you don't have one already.

  3. Navigate to https://gitlab.com/charlesbaynham/poetry-competition.

  4. Clone the poetry competition locally using SSH (git clone).

  5. Make a new branch (git checkout -b xxx).

  6. Add a poem to the repository (add a file in docs copying the format of the others, then alter docs/index.md and mkdocs.yml).

  7. Save this as a commit (git add . + git commit).

  8. Submit this as a Merge Request on GitLab, marking it as a draft (git push and read the message).

  9. Use GitLab to discuss your changes and ensure that the pipeline did not break. Fix any problems that arose.

  10. Mark the Merge Request as ready to request that your poem be added to the list.

Success means...

  • "I can pull repositories from GitLab via ssh"

  • "I am comfortable with git on the command line. I know what a commit is, what a remote is, how to push and how to pull"

  • "I know what a commit / branch / remote is. I can clone, push, pull and fetch, and know when to do so"

  • "I can handle merge conflicts when they arise. I know how to avoid them"

  • "I know the difference between git and GitLab. I can use GitLab to discuss code changes with others before I integrate them into a project. If a pipeline exists for a project, I know how to view the results"