Loading...

The Skara command-line interface (CLI) tools enables a CLI driven workflow where reviews are made either via the mailing lists or in an web browser using an external Git source code hosting provider's web application. The following CLI tools are currently available as part of project Skara:

  • git-jcheck - a backwards compatible Git port of jcheck

  • git-webrev - a backwards compatible Git port of webrev

  • git-defpath - a backwards compatible Git port of defpath

  • git-fork - fork a project on an external Git source code hosting provider to your personal space and optionally clone it

  • git-sync - sync the personal fork of the project with the current state of the upstream repository

  • git-pr - interact with pull requests for a project on an external Git source code hosting provider

  • git-info - show OpenJDK information about commits, e.g. issue links, authors, contributors, etc.

  • git-token - interact with a Git credential manager for handling personal access tokens

  • git-translate - translate between Mercurial and Git hashes

  • git-skara - learn about and update the Skara CLI tools

All above CLI tools support multiple external Git source code hosting providers.

Note: It is not necessary to use the Skara CLI tools to contribute changes. Contributors that prefer to use e.g. desktop applications, web browsers and/or IDEs that integrate with applicable external Git source code hosting providers are free to do so. See the Tools section for available options.

Overview

The following steps has to be once (the initial setup):

The following steps has to be done once per repository you want to contribute to:

The following steps has to be done for each change you want to make:

  • Create a local branch
  • Make your change
  • Create a pull request
  • Interact with reviewers
    • Update the pull request based on reviewer feedback
  • Integrate pull request

Every once in a while you will probably want to:

  • Sync your personal fork with the upstream repository

After you have used the tools for a while you will probably want to:

  • Configure commonly used Skara options
  • Setup useful Git aliases

Installing

To install the Skara tooling, simply clone the Skara repository and include the Skara Git configuration file:

$ git clone http://git.openjdk.java.net/skara
$ git config --global include.path "$PWD/skara/skara.gitconfig"

The Skara tooling will build itself the first time you use any of the Skara commands. To check that everything works run git skara help.

Updating

To update the Skara tooling run git skara update. This will pull eventual updates and rebuild the tooling if necessary.

Personal Access Token

Some of the Skara tools requires a "Personal Access Token" (PAT) to authenticate against an external Git source code hosting provider's API. These tools include:

  • git-fork
  • git-pr
  • git-token

If you do not intend to use the above tools, then there is no need to set up a PAT and you can skip this section. If you want to make use of the above tools, then please read on.

Git Credential Manager

The first step is to ensure you have a Git credential manager to store your PAT once it has been generated. See the subsections below for how to set up a Git credential manager for you operating system.

Windows

If you installed Git via https://gitforwindows.org/ then you already have a credential manager from Microsoft installed (it is bundled with "Git for Windows"). If you installed Git via some other mechanism, then install https://github.com/Microsoft/Git-Credential-Manager-for-Windows.

macOS

You already have a Git credential manager in Keychain, there is nothing to install or configure.

GNU/Linux

On GNU/Linux the recommended setup is to use libsecret and the "libsecret credential helper" in order to use GNOME Keyring as the Git credential manager. If you are using a desktop environment or distribution without support for GNOME Keyring, please see the "Manual" section.

Fedora

Fedora 29 and 30 (the only two currently supported versions of Fedora) comes with libsecret and GNOME Keyring installed by default. When you install the git package you also get the libsecret credential helper installed. To configure git to use the libsecret credential helper run:

$ git config --global credential.helper /usr/libexec/git-core/git-credential-libsecret

If you want to have a graphical utility to inspect the GNOME Keyring we recommend that you install GNOME Seahorse:

sudo dnf install seahorse
Ubuntu

Ubuntu 19.04 and 18.04.2 (LTS) (the only two currently supported versions of desktop Ubuntu) comes with libsecret and GNOME Keyring installed by default. Unfortunately even if you install the Git package you will not get a binary version of the libsecret credential helper installed (you only get the source). This means you have to compile the libsecret credential helper yourself. This is easy to do, it just requires two extra commands:

$ sudo apt install libsecret-1-dev
$ sudo make --directory=/usr/share/doc/git/contrib/credential/libsecret

Once you have compiled the libsecret credential helper you must configure Git to use it:

$ git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

If you want to have a graphical utility to inspect the GNOME Keyring we recommend that you install GNOME Seahorse:

$ sudo apt install seahorse
Manual

If you are using a desktop environment or distribution without support for GNOME Keyring, or if you want to use your own scheme for storing the PAT, then that is also supported. You can store non-sensitive data such as your username and the URL of the Git source code hosting provider in your ~/.gitconfig file in the "credential" section:

[credential "https://github.com"]
username = foobar

For the PAT itself, all Skara tools interacting with an external Git source code hosting provider's API supports the GIT_TOKEN environment variable. This means that instead of storing your PAT in a Git credential manager you can store it e.g. encrypted on disk using gpg and then set the GIT_TOKEN environment variable to the decrypted value when using applicable Skara tools. For example:

GIT_TOKEN=$(gpg --decrypt ~/pat.gpg) git pr list

Creating a Personal Access Token

To create a a Personal Access Token on GitHub go to https://github.com/settings/tokens and and click on "Generate new token". You only need to select the "repo" scope (permission). After you have generated your token, store it in your credential manager using git token store

$ git token store https://github.com
Username: <insert your Github username>
Password: <insert your "Personal Access Token", not your GitHub password>

Creating a personal fork

The first step in the Skara workflow is to create a personal fork of an existing OpenJDK repository. Your personal fork is a copy of the original OpenJDK repository. Having a personal fork allows you to experiment with changes without affecting the original OpenJDK project. Having a personal fork also enables you to create pull requests targeted towards the original OpenJDK repository.

Creating a personal fork is easy. Either use the GitHub web UI or use use the Skara CLI tooling. The following command will for example create a personal fork of the jdk repository.

$ git fork https://github.com/openjdk/jdk

The above Skara CLI command git fork will also clone your personal fork to a local repository on your computer. One common way of structuring your local repositories is by following the domainname and path convention. This is not a requirement, but has proven to be a useful way of keeping track of multiple repositories. For an example, see below:

$ tree
.
├── git
│   └── github.com
│       ├── edvbld
│       │   ├── jdk
│       │   └── loom
│       └── openjdk
│           ├── jdk
│           ├── loom
│           └── valhalla
└── hg
    └── hg.openjdk.java.net
        ├── code-tools
        │   └── jtreg
        └── jdk
            └── jdk

In the above example you can see that I have two personal forks of the openjdk/jdk and openjdk/loom repositories:

For convenience I also have local clones of three upstream OpenJDK repositories: jdk, loom and valhalla.

Creating a local branch

To be able to work on mulitple changes concurrently you will want to create a local Git branch per change. Creating a local branch in Git is very easy:

$ git checkout -b <branch-name>

If you are using Git 2.24 or newer then you can also use the more recent git switch command which reads a bit more natural:
git switch --create <branch-name>

Listing local branches

A common way of structuring your local branches is to name them after the issue they correspond to, for example JDK-8237566 (or just 8237566). After making a few changes you will start to have a couple of local branches. You can list your local branches with git branch:

$ git branch
  JDK-8237566
* JDK-8149128
  JDK-8077146
  master

A perhaps nicer way to visualize your branches is to view them in all a commit graph with the help of git log:

$ git log --format=oneline --graph --all

Switching branches

You can switch between local branches using:

$ git checkout <branch-name>

If you are using Git 2.24 or newer then you can also use the more recent git switch command: git switch <branch-name>

Multiple local clones

If you are used to having one local clone of a repository for each change you are working on then that is also supported. The only difference is that you first create a local clone of your personal fork, then create a local branch in that local clone. Fortunately the Skara git fork command is idempotent - if you already have a personal fork then you will just get that one. Therefore the following commands can be run by those preferring to have one local repository per change they are working on:

$ git fork https://github.com/openjdk/jdk JDK-8237566
Fork available at: https://github.com/edvbld/jdk
Cloning https://github.com/edvbld/jdk...
Cloning into 'JDK-8237566'...
remote: Enumerating objects: 1019523, done.
remote: Total 1019523 (delta 0), reused 0 (delta 0), pack-reused 1019523
Receiving objects: 100% (1019523/1019523), 372.46 MiB | 4.99 MiB/s, done.
Resolving deltas: 100% (761166/761166), done.
Updating files: 100% (68663/68663), done.
Adding remote 'upstream' for https://github.com/openjdk/jdk...done
$ cd JDK-8237566
$ git checkout -b JDK-8237566
Switched to a new branch 'JDK-8237566'
  • No labels

Terms of Use
• License: GPLv2
• Privacy • Trademarks • Contact Us