- Contribution Guide for Kendrick
- Setup Iceberg
- Fork the Kendrick repository
- Load your fork version of Kendrick in your image
- Add main Kendrick repository as remote
- Send some changes to the original Kendrick repository
- Pull changes from original to fork
- Release management (not used at the moment)
- Branch management (to be defined)
Contribution Guide for Kendrick
This file is currently not complete but will be improve step by step.
In order to contribute to Kendrick on github we are using Pharo 9.0 and Iceberg.
You need an ssh key in order to commit on github. Open Iceberg tool, and then click on the settings. Check the box : "Use custom SSH keys".
Fork the Kendrick repository
All changes you'll do will be versionned in your own fork of the Kendrick repository. Then, from your fork you'll be able to issue pull requests to Kendrick, where they will be reviewed, and luckily, integrated.
Go to Kendrick 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 kendrick.
Load your fork version of Kendrick in your image
In your Pharo 9.0 image, load now the last development version of Kendrick :
Metacello new githubUser: 'XXX' project: 'kendrick' commitish: 'master' path:'src'; baseline: 'Kendrick'; onWarningLog; load
where you replace XXX with your github user name.
PS: at the moment, we have only one master branch, so all development happens on this branch. We will use two branches when we release a first version of Kendrick.
If you have problems loading with the previous script due to network issues, use the following one:
| count | count := 1. Transcript open. [ true ] whileTrue: [ [ ^ Metacello new githubUser: 'XXX' project: 'kendrick' commitish: 'master' path:'src'; baseline: 'Kendrick'; onConflictUseLoaded; onWarningLog ; load. ] on: IceGenericError "Failed to connect to github.com: Interrupted system call" do: [ : ex | Notification signal: String cr , ex description, String cr , 'RETRYING ', count asString. (Delay forSeconds: 2) wait. ex retry ]. count := count + 1 ]
Add main Kendrick repository as remote
Open Iceberg, open Kendrick repository, click on repositories, then + button (add remote).
Remote name: upstream
Remote URL: https://github.com/UNU-Macau/kendrick.git
Send some changes to the original Kendrick repository
From Pharo Iceberg
Please use a different branch for each PR that you want to send to the Kendrick project. After doing the modifications in your image, open Iceberg tool, commit the changes of your branch in your Kendrick repository. Cherry-pick the modifications that you want to include in your commit. Then push your commit to your fork. It's more convenient to divide your changes in meaningful and simple commits, which makes it easier to check for those who need to proofread it.
From GitHub UI
In the GitHub interface, create a Pull Request (PR) from your commit. You have to give some information about what is the purpose of you pull request. Then submit it to Kendrick main repository. This will notify Kendrick core developers team that an improvement or bug fix is pending.
As the main core developers, you have to review the open PRs. When merging the pull request, select Create a merge commit not squash and merge. Try to avoid (except in case of emergency) to review your own commits.
Pull changes from original to fork
You can proceed in two different ways to update your fork. You can either use github's web interface, or entirely from pharo/Kendrick.
From GitHub GUI
If at some point, you see than the original Kendrick repository is ahead from your own fork (2 in the following picture) you can synchronize your own repository with all the newest features add to the original using compare (3)
To compare you can define sources (1) and target (2) for the update. Once it's done, you can use the pull request mechanism (3) to merge the original Kendrick code to your own.
The last step in this process, you'll just have to go back to your Kendrick Pharo a pull into your Kendrick image in the VM.
Sync your fork with the Kendrick main repository
After a while, changes from other developers are integrated in the main Kendrick repository and your fork became out of sync. In order to do that, you need the fetch the last modifications from the main Kendrick repository, merge them in your image and then push them in your fork repository.
In your own local machine containing your cloned fork directory (i.e. you forked first Kendrick, and then executed "git clone ..." your own fork), you should always synchronize your GitHub fork with the latest modifications in the upstream before pushing any updates (pull requests). This can be done from command-line:
git remote add upstream https://github.com/UMMISC/kendrick.git git fetch upstream git checkout master git rebase upstream/master git push -f origin master
You have also the possibility to delete your fork and fork again the main Kendrick repository.
Ounce your pull request is integrated, some cleanups are maybe required:
- remove your branch from your fork
- close the issue (tips: you can automatically close the issue n, by inserting the sentence: close #n when you merge your pull request).