Contribute a fix to Pharo
Watch the video from the Pharo TechTalk February 2018 for a step by step tutorial.
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.imageIf 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/get-files/70/pharo.zip
- VM: http://files.pharo.org/get-files/70/pharo-win-stable.zip
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.
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_rs- in macOS, execute in your shell:
ssh-add -K ~/.ssh/id_rs- 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.
For windows users: you may encounter some problems to manage files with long names. In case you have problems, please try with Option 2.
From your iceberg window, click on "Clone repository" and complete the required fields:
- Remote URL: [email protected]:[YOUR_GITHUB_USER]/pharo.git
- Local directory: The place where you want to store it (you can let default value if you do not want to point to a specific place)
- Code subdirectory: src
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 [email protected]:[YOUR_GITHUB_USER]/pharo.gitOtherwise, you can use your preferred graphical tool such as SourceTree, GitKraken, SmartGit, GitExtensions, TortoiseGit, etc.
From your iceberg window, click on "add local repository" option, and complete the required fields:
- Local directory: The place where your git clone is (WITHOUT including "src" directory, this will go in the next field)
- Code subdirectory: src
You may need to invoke "Synchronize repository..." if you see uncommited changes. At the end you will see something like this:
Once iceberg is configured, you need to tell it about pharo-project (the repository you forked on github) to be able to submit changes. 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. You need to add pharo repository as a remote ([email protected]:pharo-project/pharo.git).
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
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 +Create 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).
Commit your changes. You should Commit and Push so that your changes get pushed to your github repository.
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.
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.
Some cleanups are required:
- remove your branch from your fork
- close the issue