How to contribute to Glamorous Toolkit through a GitHub pull request

You have been using the ready made GT distribution for a while now, writing your own code, examples, views and actions, occasionally trying to extend or modify existing code. You have something that you would like to propose for addition to GT itself. Maybe you fixed a bug.

As GToolkit is being developed on GitHub, you will need to do a pull request. This is a standard and widely used way to contribute to open source software.

Requirements

You need a GitHub account, with SSH keys, the command line git executable, SSH agent setup as well a a personal access token.

There are two ways to access remote GitHub repositories, via two different origin URLs. There are HTTPS URLs in the form of https://github.com/owner/project.git and SSH URLs in the form of git@github.com:owner/project.git, both are equivalent and refer to the same remote server.

You need a username and a personal access token as password in the first case and SSH keys for the second case.

To allow unattended access (i.e. to prevent any interactive prompts) you need a credentials helper in the first case and an SSH agent in the second case.

Make sure clone, pull, commit and push on the command line before continuing.

Let GtGitHubTokenHolder Object subclass: #GtGitHubTokenHolder instanceVariableNames: '' classVariableNames: 'filePath token' package: 'GToolkit4Git-Tools' know about your personal access token. You can set it directly as a string using GtGitHubTokenHolder>>#token: token: aString "Set the token that I hold to aString. Note that this also means the token will be saved along with the image" token := aString trimBoth , let it be read and copied from a file using GtGitHubTokenHolder>>#readAndCacheTokenFrom: readAndCacheTokenFrom: aFileReference "Read and set my token from aFileReference. Note that this also means the token will be saved along with the image" self token: aFileReference asFileReference contents lines first or let is be read each time from a file using GtGitHubTokenHolder>>#readTokenEachTimeFrom: readTokenEachTimeFrom: aFileReference "Set the file from which I will read the token to aFileReference. Note that the token will not be saved along with the image, but read every time it is needed." filePath := aFileReference asFileReference . In the last case the token is not stored in an object that is part of the image.

Example

Let's use a simple example to make things more concrete. Though there already exists a preview inspector gt view for Color, you like circles way more and want to add such a view.

Color red
  

Here is the source code of such an addition.

gtCircleFor: aView file:///gtView ^ aView explicit title: 'Circle'; priority: 50; stencil: [ BlElement new geometry: BlCircleGeometry new; background: self; size: 64 @ 64; margin: (BlInsets all: 10); yourself ]

You want to add this as Color>>#gtCircleFor:

Since this is an extension, you look at the other gt views on Color and you notice most of them belong to GToolkit-Inspector so you decide to do the same, i.e. set the method category to *GToolkit-Inspector. You test your extension and you are happy.

Contributing

Start clean

It is best to start with a fresh, clean, fully up to date, ready made distribution GT image from https://gtoolkit.com/download/ and to launch your image from the command line.

Find the repository we need

Since no repositories are defined we first need to find out which repository we need, since there are many of them. When the ready made image was created, some essential information of each repository was recorded. See the History inspector tab in IceRepository Object subclass: #IceRepository instanceVariableNames: 'name workingCopy index commitsInPackageCache' classVariableNames: 'Registry RepositoryClass' package: 'Iceberg-Core' . Note that the history is not present in a developer image built from sources.

We need to find which repository holds our package. This can be done using GtGitRepositoryRegistryHistory>>#repositoryIncludingPackage: repositoryIncludingPackage: packageName ^ self records detect: [ :each | each includesPackageNamed: packageName ] ifNone: [ nil ] as follows.

GtGitRepositoryRegistryHistory instance repositoryIncludingPackage: 'GToolkit-Inspector'
  

Now that we know this, we have to restore the gtoolkit-inspector repository.

Create your fork

To do a pull request you need your personal fork of the repository you want to contribute to. You also need to make your changes in a feature branch.

Go to the History tab of IceRepository Object subclass: #IceRepository instanceVariableNames: 'name workingCopy index commitsInPackageCache' classVariableNames: 'Registry RepositoryClass' package: 'Iceberg-Core' , select gtoolkit-inspector and click the Fork button.

When you open the GT Git tool, you should now see this repository. It was forked, cloned, created and registered.

The pull request process works my first committing to this copy or fork in your own GitHub account and then asking for those changes to be considered for inclusion.

Create a feature branch

Before committing our changes we also need to create a feature branch which is like a name indicating the intent of our changes. Here we name the new branch feature-color-gt-view-circle by toggling to the inspector view in the Git tool and going to the underlying repository.

When on the Branches inspector tab a + button appears that allows you to create and switch to a branch by specifying its name.

Our forked repository is now switched to our feature branch. We push this branch so that it appears in our forked repository on GitHub.

Make your changes, commit and push

Now we are ready to add our code and make the actual change in our image (see the Example section above).

Going back to the GT Git tool, we can see our repository with our change ready to be committed on our branch. Go ahead and commit. The first line of the last commit on the branch will be used as comment for the pull request later on.

Next we need to push the changes in our fork so that our changes become visible in our forked repository on GitHub. Do a push.

Create your pull request

Finally we can create the actual pull request, again using the repository inspector view.

If all went well, you can see your pull request appear in the master repository. The team behind GT will either accept your PR to integrate it, or will communicate with you to discuss further options.