Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Contribute a fix to Pharo
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:
- Image: http://files.pharo.org/image/70/latest-32.zip
- VM: http://files.pharo.org/vm/pharo-spur32/win/stable-20170720.zip
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.
To be able to contribute to Pharo, you need a pharo git repository. A freshly downloaded Pharo image has iceberg installed, and a pharo repository pre-configured. However, since pharo is a system repository and not everybody would like to edit it, it is hidden by default:
Click on the little button on the top right to access iceberg settings and configure as visible the system repositories.
And activate the option:
Current iceberg version does not refresh automatically. Close Iceberg and re-open it to see the changes take place.
Pro Tip: if you want to always see it, even for new images, click on Store Settings!
Now you should see the hidden system repository as follows:
The red line indicates there is a repository that misses a local repository. If you click on the repository, you'll be given three options:
- Edit...: to use when you already have a pharo clone
- Clone: if you want iceberg to automatically clone a repository for you
- Forget: to remove the repository from the image
Option 1: if you want to clone a fresh pharo repository
This is broken so far...
Option 2: if you make (or already have) an external pharo clone
- Make an external clone if you don't have one
For windows users: you may encounter some problems to manage files with long names. Use the following workaround to solve them.
From the command line, you can clone your fork of the pharo repository using the following:
$ git clone https://github.com/[YOUR_GITHUB_USER]/pharo.git
Otherwise, you can use your preferred graphical tool such as GitKraken, SmartGit, GitExtensions, TortoiseGit...
- Import your clone into iceberg
Click on the Edit... button and the following dialog will appear:
Browse your disk and select the following:
- Local directory: the directory of your clone
- Code subdirectory: put the string src, since pharo code is in a src subdirectory
Once that is done, you'll see that iceberg refreshes and shows you the correct data:
Tell iceberg about your fork
Once iceberg is configured, you need to tell him about your pharo's repository and your fork. Remote repositories are called remotes in git. You can configure them by going to the remotes tab in the repository.
You can click on the Add remote option and configure a remote with a name and repository url.
- if you cloned pharo-project/pharo: you need to add your fork as a remote.
- if you cloned YOUR_FORK/pharo: you need to add pharo repository as a remote (email@example.com:pharo-project/pharo.git).
Finally, the most reasonable way to work is to configure pharo's repository as a default pull remote and you fork as default push remote. Do a right click on each of the remotes and select Make default pull/push remote respectively.
Step 1: 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 2: 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
Iceberg already automatizes some of these things. Go back to iceberg, right click on the pharo repository and go to the Pharo entry. You'll see the option Create new branch from Fogbugz issue.
That will open a popup where you can set the number of the issue you created, and when focus is lost, it will autocomplete the issue name.
Click on accept and iceberg will create and checkout the new branch.
To commit your changes into your branch, select the repository and do a synchronize.
That will calculate the differences between the checked-out branch and your image, show you the tree with the differences and let you commit (and push).
Step 3: 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