Contribute a fix to Pharo

Marcus Denker edited this page Jul 9, 2018 · 21 revisions

This tutorial shows how to contribute to Pharo using Iceberg. For more information about Iceberg, check its wiki in here.

Video Tutorial

Note: This textual tutorial is also available as a video in youtube.

Step 0: Setting up the development environment

Download and launch latest 7.0 pharo:

If you have a nice command line environment (wget, readline, bash), download latest development pharo using zeroconf.

Pro tip: If you're on windows and you want a nice command line environment, install msys

wget -O- get.pharo.org/70+vm | bash
./pharo-ui Pharo.image

If you don't have a command line environment, you can download both image and vm manually from the following links:

Fork the Pharo repository

All changes you'll do will be versionned in your own fork of the pharo repository. Then, from your fork you'll be able to issue pull requests to pharo, where they will be reviewed, and luckily, integrated.

Go to pharo github's repository and click on the fork button on the top right. Yes, this means that you'll need a github account to contribute to pharo, yes.

Setup Iceberg

To be able to contribute to Pharo, you need a pharo git repository.

Pre-requisite: Setting credentials

You will need to set a valid set of credentials in your system to be able to work with Pharo. In case you use SSH (the default way), you will need to make sure those keys are available. In case they are not (and you will notice as soon as you try to clone a project or commit a change into one), you can add them following this steps:

  • in linux, execute in your shell:
    ssh-add ~/.ssh/id_rsa
  • in macOS, execute in your shell:
    ssh-add -K ~/.ssh/id_rsa
  • in windows is more complicated, you may need to generate a pair of keys (that needs to be uploaded to your account on github).
    • You can follow instructions on how to generate your keys here.
    • Then you need to go to settings browser, search for "Use custom SSH keys" and complete your data there.
    • Alternatively, you can execute in your image playground:
IceCredentialsProvider useCustomSsh: true.
IceCredentialsProvider sshCredentials
	publicKey: 'path\to\ssh\id_rsa.pub';
	privateKey: 'path\to\ssh\id_rsa'

Pro Tip:: this can be used too in case you have a non default key file, you just need to replace "id_rsa" with your file name.

Step 1. Setting up your repository

Pharo7 image comes with a pre-configured Pharo repository. This repository will most be in state "Local Repository Missing". This means that the image does not find a pharo clone in your disk. You can have more details of it in the Glossary.

Repairing local repository missing

To solve this situation, you need to rebind your repository with a clone in disk. You will be proposed with the repair menu item/button.

And clicking on it will show you the repair view, showing an explanation of the current situation and some proposed solutions:

You can then choose to search in your disk for an existing clone or to clone a new repository.

Once the repository has a clone, it will check the repository status and most probably you'll find out that your repository is in Fetch required state.

Solving the Fetch Requiredg

Fetch Required means that your image was built from a commit that cannot be found in your repository. In other words, we need to update your repository, doing a fetch (more details of it in the Glossary).

If you click again on the repair action, you'll see that there are other repair actions available. Usually, if you already have all your remotes correctly configured, doing a fetch will put you in a **Detached Working Copy ** state.

Step 2: Opening an issue

The process of contributing to pharo starts by opening an issue. Please, address yourself to the fogbugz issue tracker.

Click on New Case and:

  • Put a title to it
  • Select the corresponding sub-project
  • Set Pharo7 as Milestone
  • Set a category
  • Set a priority
  • Write a description
  • And finally click on open

Step 3: Work on your image and push your change

Once you have modifications in your image, it's time to push those changes to your fork and make a pull request. To do that, we enforce the following process:

  • you create a local branch for the issue
  • you issue a pull request of that issue to the main pharo development branch

Solving the Detached Working Copy

Detached Working Copy means that the image commit does not correspond with the repository commit (more details of it in the Glossary). At this point, we need to synchronize both to be able to work.

Most of the times, the easier thing to do in this case is to just create a new branch. If you already know which issue you'll be working on, you can create a branch using the "New branch from issue" option. Otherwise, a nice alternative is to create a temporary branch like temp/synch that you can later on remove.

Step 4: Issue a pull request

Once you have done and commited all your work, you need to push it and create a pull request. Right click on the repository and go to the Github plugin.

Select the option Create pull request and select as target branch pharo's development branch.

And issue the pull request!

Pro Tip: It is recommended to put the issue url in the pull request description.

Then go back to your issue entry in fogbugz, set its state to Fix Review Needed and put a link to the pull request as well as other comments related to the solution as description.

Step 4: Follow your pull request

If you go to github, you'll see your pull request open and that some checks are running.

You can click in details to go see the jenkins job validating the pull request.

Step 5: Once your pull request is integrated

Some cleanups are required:

  • remove your branch from your fork
  • close the issue
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.