- Contribution Guide for Kendrick
- Release management (not used at the moment)
- Branch management (to be defined)
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".
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.
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;
loadwhere 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 ]Open Iceberg, open Kendrick repository, click on repositories, then + button (add remote).
Remote name: upstream
Remote URL: https://github.com/UNU-Macau/kendrick.git
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.
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.
You can proceed in two different ways to update your fork. You can either use github's web interface, or entirely from pharo/Kendrick.
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.
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 masterYou 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).