Skip to content

Github tutorial

Jump to bottom
Fabien edited this page Jun 29, 2022 · 6 revisions

Github tutorial for GNAP participants

This page is here to help you participate in the GNAP project. Git is a versioning control system that helps when many contributors work simultaneously on a project. Github is a centralized service (managed by Microsoft) built on top of git and that provides ergonomic tooling, especially for issue management.

Our goal is to provide a better governance of the project, as git allows transparency in the design decisions, based on an extensive auditing trail (all commits are versioned). Github is very useful to search within issues and organize the work items. Another benefit is that you'll get a weekly activity summary.

Please note that our use of github is simplified, as we have one main file called draft-ietf-gnap-core-protocol.md where changes are made. We don't detail all the possibilities provided by git or github.

The proposed workflow is specific to our use case within the IETF working group.

Dependencies

Github account (mandatory)

You should have (or create) a github account. Note that github has announced passwords will be deprecated and mandate the use of personal tokens or SSH key will be required.

Git and/or Github CLI (optional)

The git CLI or the github CLI are available for download on your computer. The difference between the 2 CLIs is that github CLI provides support for features specific to github (e.g. issues). Commands are required if you want to commit changes.

Docker (optional)

See building instructions, the easiest is to have docker installed. But you can also have all build dependancies installed on your computer if you prefer.

Vocabulary

There's a fair amount of specific vocabulary, on git and github.

The terms which are most important: issue, PR (pull request), clone/fork, commit, branch.

In this document, we also differentiate between editors (i.e. maintainers) and the rest of the users. We focus on users, there may be additional tools to consider for editors (for instance github actions).

Graphical interface

Github provides a fairly intuitive user interface, from which you can view files, issues, PR etc.

Project level buttons

You may :

  • watch the project: this corresponds to high level notifications, but you can also choose to follow specific issue if you want to avoid to much distraction
  • star it: it measures the "popularity" of the project. A star is always appreciated.
  • fork: use this when you want to clone the project into your own personal repository. This is useful to get a local version that you can open into your editor of choice (e.g. Visual Studio, Atom, whatever), make changes, and commit. The readme describes how you can build locally the HTML files (through docker).

GitHub Interface Tabs

This means that the most common operations can already be managed through their web interface, most actions are available through the tabs on the top of the screen.

In particular, you'be using the following tabs:

  • Code: it's where you find the source files on which commits are made, especially draft-ietf-gnap-core-protocol.md which is the document that gets edited. The readme file explains how you can build locally the project (useful to generate locally an HTML version; please note that derived files are not committed to the repo). For a more advanced usage, you can view a specific version based on branches (main being the official one, but there can be branches dedicated to a specific work) or tags (to refer to a specific version).

  • Issues: that's most likely the place where you'll spend most of your time. You can search for issues (through text search or based on tags), participate in the discussion by commenting one issue, open new issues (look for the green button). Please also note that you can subscribe to issues, to be notified when there is a new comment.

  • Pull requests: that's where changes to draft-ietf-gnap-core-protocol.md are proposed and reviewed. If rough consensus is achieved, the change will be merged with the previous version, on the main branch.

Participating in discussions (issues and PRs)

Here again participating in discussions generally requires little knowledge of git or github.

Commenting on open issues

You first need to be logged-in and open an issue. Each issue is assigned a specific URL and identifier. It also has a title, and a follow-up discussion. You can comment through the text editor. Remember that it is based on markdown, so you have shortcuts to reference other issues (#), other users (@), link to URLs, etc. Please refer to the styling guide for more information.

You can edit your comment if necessary.

The editors manage the status of the issue, and gather consensus before closing. When closed, there should be a really good reason to reopen, so please contact the editors first.

Creating a new issue

Remember that general discussion should be on the IETF mailing list. It's often a better process to first discuss your concerns there, before opening new issues. But once you clarified what you expect, feel free to open a new issue:

  • Please check first that it doesn't exist already (otherwise comment on the existing one)
  • Please be as specific as possible

Reviewing a PR

A PR means that a commit of the specification document has been made. So there's a process to review it. Github provides tools to make diffs between versions, in green ++ and red -- and an editor to make your review (either for the global PR or on specific lines).

The author of the PR may commit new changes to take into account those feedbacks, in which case new versions of the files will appear. When consensus is achieved, the PR will be flaged as pending merged, and merged after 7 days if no further comment is made.

Committing a change

PR process

Committing a change proposal doesn't mean it will be accepted. Your proposal gets into a workflow called PR (pull request). After this review, changes may be merged into the core specification, and the related issues and PR are closed. The editors are the one managing this workflow to make sure the text remains consistent, and systematically inform the members of the working group via the IETF mailing list.

Note: editorial PRs (i.e. that don't change the requirements) may follow a lighter process.

Command line instructions

The process for committing a change requires the use of the CLI (see dependencies).

  1. To make sure you have the permissions, please fork the project into a personal github repository (https://github.com/YourUserName/gnap-core-protocol)
  2. Clone it locally (i.e. on your computer) git clone https://github.com/YourUserName/gnap-core-protocol
  3. Get into your local directory gnap-core-protocol and create a new remote for the upstream repo git remote add upstream https://github.com/ietf-wg-gnap/gnap-core-protocol
  4. Fetch updates with git fetch upstream; the first time you clone the repository, this won't change anything, but this step ensures that you are working against the latest version from the working group
  5. Create a new branch, ideally name it so that it is clear what is being addressed, like "token request formatting" as "token-request-format" in this example) git checkout -b token-request-format upstream/main
  6. Make the changes to the specification, using your preferred editor. Check that you apply editor's config (or apply eclint fix).
  7. Build locally the HTML and check that the file displays correctly using docker-compose up or ./build.sh
  8. Commit the changes using git add draft-ietf-gnap-core-protocol.md and git commit -m with a detailed comment
  9. Push the new branch to your fork on GitHub git push -u origin token-request-format
  10. Nagivate to your fork (https://github.com/YourUserName/gnap-core-protocol) and create a pull request against the working group's repository on branch ietf-wg-gnap:main; this will be the default option from GitHub

It will appear in the Pull request tab, so that people can comment. You may also allocate specific reviewers to your PR. If people make comments that you want to take into account, you can commit the changes again and they will appear in the PR.

Before working on your next PR, you can refresh the forked repository and follow the steps again.

Temporary HTML preview / official drafts

The editors have put an automatic process in place that uses github actions. Each commit will spawn a new build process, so that the markdown file renders an HTML preview deployed on netlify. This is for convenience only. Please only refer to official drafts (published on https://datatracker.ietf.org/wg/gnap/documents/) in your issues or mails.

Reference documents

Clone this wiki locally