Skip to content

Outreach student your first pr

Jump to bottom Edit New page
James O. D. Hunt edited this page May 4, 2023 · 2 revisions

Raising your first PR

Intro

Raising your first Pull Request (PR) can be slightly scary and even rather frustrating as there are lots of points to think about.

However, fear not! Your mentors are there to help you.

Recommended first PR

Find the smallest possible change you can make to any file in any of the Kata repositories:

When we say smallest, we mean smallest: a one line change or even a single letter typo is perfect for a first PR!

Note: Your first PR should be an individual contribution. Every student should raise a minimal first PR. However, for your "main" task, you may decide to work in small teams. The process for working in teams with a single git fork is different so please read the following:

Finding something to change

Mechanics of creating a PR

  • Read the Kata Containers contributing guide

  • Fork a copy of the repository you want to change.

    For example, if you want to change something in the main repo:

  • Create a local clone of the main kata repo (not your fork):

    $ git clone https://github.com/kata-containers/kata-containers

  • Change into the clones directory or folder:

    $ cd kata-containers/

  • Add a git "remote" for your fork (aka an alias to your fork's URL). For example, since my GitHub username is jodh-intel, I might run this:

    $ git remote add james-github https://github.com/jodh-intel/kata-containers

  • Create a branch for the work you want to do. For example, if you wanted to fix a spelling mistake, you might create a branch called fix-typo:

    $ git checkout -b fix-typo origin/main

PR Advice

Tips

Ensure all commits are in the correct format

The Kata Containers CI systems require that all commits are in the correct format. If they are not, the CI will fail and your PR cannot be landed until you correct the commit format.

GitHub email address and your commit email address

GitHub itself will get upset if you make commits using a different email address to the "primary" email address you specified for your GitHub username.

Adding a new file

If your PR adds a new file and that file is not a documentation file, you will need to add a copyright and license header.

License header

All files must have an Apache 2.0 SPDX header.

Copyright header

All files must have a license header showing the year(s) and who owns the copyright (who created the file).

Notes:

  • If you work for a company or organisation or are studying at an educational establishment, the copyright will generally belong to that organisation, so their name should be specified. However, you should check with the organisation to see what their policy is.

  • If you are not affiliated with an organisation, the copyright will generally belong to you so specify your full and actual name (not a nick-name or alias).

  • If in doubt, ask someone!

License and copyright header examples

Here's an example from a rust file:

// Copyright (c) 2022 Intel Corporation
//
// SPDX-License-Identifier: Apache-2.0
//

And here's an example from a shell script:

#!/usr/bin/env bash
#
# Copyright (c) 2022 IBM
#
# SPDX-License-Identifier: Apache-2.0

And here is one more example from a Dockerfile:

# Copyright (c) 2020 Eric Ernst
# SPDX-License-Identifier: Apache-2.0

See the following for further info:

Updating your PR

Golden rule: You do not need to raise a new PR every time you make changes!

At some point, you will need to update your PR. Maybe the community made some suggestions.

To do this:

  • Update the files you have modified as necessary.
  • Commit your changes: git commit -asm "review changes".
  • Merge the "review changes" commit with your main commit:

    • Run, git rebase -i main.

    • Leave the first commit at the top (your "main" commit) alone (it should show "pick" next to it).

    • Change your review commit(s) from "pick" to "squash".

    • Save and quit the editor.

      Note: If the rebase fails with conflicts, speak to your mentors if you do not know how to resolve the issue.

    • Re-test your code by building it, running it and running any tests.

    • Update the PR by force pushing the changes back to githhub: git push -f

See also

Add a custom footer
Add a custom sidebar
Clone this wiki locally