Skip to main content

How to Contribute to Cormas

This tutorial will teach you how to contribute to Cormas by resolving issues and making pull requests to our repository on GitHub.

Prerequisite: Before going any further, you need to make sure that you have a GitHub account and that you can authenticate with SSH keys. Follow those steps from our GitHub tutorial:

  1. Create a GitHub account
  2. Generate SSH keys

Select an issue​

All issues Cormas-related issues are recorded on our issue tracker. You can open it be clicking on the "Issues" button on our repository.

You will see the list of open issues. Most issues will have one or multiple labels associated with them. If you are a newcomer, we recommend that you start with good first issue label. Those issues are selected by experienced developers as a recommended practice for new contributors. They are usually small and easy to resolve.

In this tutorial, I will be working on issue #699 which asks to add a "Browse" option to the context menu of the entity. I click on the issue, read its description and the discussion section. Then I leave a comment indicating that I am working on it. This will prevent other contributors from taking on the same issue.

Create a fork​

Since you don't have access to commit to Cormas repository directly, you must create a fork - a copy of this repository on your GitHub account. You will modify this fork and then submit the changes to the original repository as a pull request. We (Cormas developers) will review your proposed changes and either accept (merge) them or ask you to change something. You can create a fork by clicking on the "Fork" button in the top-right corner of our repository.

You can leave all the default settings (repository name, your GitHub account, description, etc.) but be sure to uncheck the checkbox "Copy the master branch only" because you will be working on the dev branch.

After you click on the "Create fork" button, the new fork will be created and opened automatically.

You will see that repository is now linked tou your account. There will also be an indication that the master branch of your fork is up to date with the master branch of the original cormas repository.

Create a new Pharo image and load Cormas​

Create and open a new Pharo image. In the Playground, execute the following script but replace my username (olekscode) with yours:

Metacello new
    repository: 'github://olekscode/cormas:dev';
    baseline: 'Cormas';
    load.

This step is the same as the Loading Cormas section of the installation tutorial but instead of loading the master branch of the central repository with github://cormas/cormas, we load the dev branch of our fork with github://<username>/cormas:dev.

Specify your SSH keys​

Now we must specify the location of our SSH keys to make sure that Pharo image can authenticate to GitHub and make commits from your account. If you don't have the SSH keys yet, please follow the Generate SSH keys step of our GitHub tutorial. Click on "Browse" in the world menu and then on "Git Repositories Browser" (a tool also known as "Iceberg").

Now click on the "Settings" button in the top-right corner of the repositories browser.

In the settings browser, select "Credentials", check the "Use custom SSH keys..." checkbox and make sure that both public and private SSH keys point to the correct location on your computer. Now you can close the settings browser, your changes will be automatically saved.

Create a new branch for issue​

It is possible that while you make your changes, someone else will push their own changes to Cormas. Then you will be forced to pull those changes and resolve potential conflicts before pushing your own changes. To simplify this process, it is a good practice to create a separate branch for the issue that you are resolving and, once you are done, make a pull request merging this branch into the original branch (dev).

Pharo automates all this process for you. In "Git Repositories Browser" (Iceberg), right-click on cormas, select "GitHub" and then "Create new branch for issue".

You must now specify the remote repository that has the list of issues. This should be the central Cormas repository. But at this point, Pharo only has the link to your remote repository. So we must add another remote. To do that, click on the "Add remote" button (the one with a green plus "+").

Now give the name to your remote. I call mine "cormas" but you can choose any name that you like. Remote URL should be the SSH address that you copy on GitHub. For Cormas repository it's "git@github.com:cormas/cormas.git". Once you have completed both fields, click on the "OK" button.

Sometimes, this action will produce an error similar to the one below. This is a bug of Git Repositories Manager. You can ignore it and simpy close the debugger window.

Now you can select Cormas repository from the list of remotes. Write the issue number in the second field. The number of my issue is 699 - it's the issue that I selected in the Select an issue section of this tutorial. If you did everything correctly, the branch name field will be auto-completed with your issue title that will be automatically retrieved from GitHub.

Once you click "OK", the new branch will be created. You can see the name of this branch next in the "Branch" column of the "Repositories" table.

Make changes​

Now you can write the code to resolve your issue. In my case, I have to add a "Browse" button to the context menu of all entities in a spatial grid visualization. To do that, I make the following changes (you do not need to understand them because your changes will be different anyway).

First, I add a new subclass of CMSpaceContextMenuCommand and call it CMBrowseSpaceContextMenuCommand.

CMSpaceContextMenuCommand << #CMBrowseSpaceContextMenuCommand
	slots: {};
	package: 'Cormas-UI-Commands'

I implement three required methods: name, icon, and action (notice that in the name method I call the tBrowse method of translator which will return the string in a different language depending of which tranlator is used).

CMBrowseSpaceContextMenuCommand >> name
	^ translator tBrowse

CMBrowseSpaceContextMenuCommand >> icon
	^ self iconNamed: #smallSystemBrowser

CMBrowseSpaceContextMenuCommand >> action
	^ owner class browse

Then I register my new command by adding it to the collection inside the CMBrowseSpaceContextMenuCommand >> contextMenuItemsFor: method.

CMBrowseSpaceContextMenuCommand >> contextMenuItemsFor: anEntity
	^ {
		CMInspectSpaceContextMenuCommand forOwner: anEntity .
		CMBrowseSpaceContextMenuCommand forOwner: anEntity
	}

I verify that my changes are correct and everything works well. Now I am ready to commit and push my changes.

Commit and push​

If you open "Git Repositories Browser" after making your changes, you will see that cormas repository is green and has a status "Uncommitted changes" (sometimes we say that it's a "dirty repository").

Double-click on cormas repository to see the list of packges. The ones that you modified will also be green. You can now click on the "Commit" button in the top-left corner.

Carrefully go through the list of changes that you are about to commit. If there are some changes that are not supposed ton be included into this pull reques, make sure to uncheck them. Then write a meaningful commit message. If you are fixing an issue, it is a good practice to start your message with a special word "Fixed" followed by a space, a hash, and the issue number. For example, my message is "Fixed #699. Added a Browse button to the context menu of all entities". GitHub will automatically detect the "Fixed #699" part and close issue #699 as soon as your pull request is merged (accepted). Once you wrote your message, click on the "Commit" button in the bottom-right corner.

At this point, you might get a list of critiques - optional suggestions on how to improve your code. Try to take them into account, then click the "Update" button. When you are done, you can click on "Commit". You can also ignore the critiques if you find them irrelevant and click on "Commit" without fixing them.

Click on the "Push" button in the top-left corner of teh "Working copy of cormas" window.

Make sure to select your own remote repoository and not the central repository of cormas. Otherwise your push will be rejected because you don't have the access rights to push to Cormas directly (also, it is not a very good practice, even for the core developers). Then click on the "Push" button in the bottom-left corner.

Open a pull request​

Now open GitHub in your web browser and go to your fork of Cormas. You should see a yellow message saying that there is a branch with a recent push. Click on "Compare & pull request".

Make sure that you are making a pull request to the dev branch and not to the master branch. We do not accept any PRs to master.

Congratulations! You have just submitted your first pull request :)

We will review it as soon as we can and either merge it (accept your changes) or ask you to modify something. If nobody reacts to your PR in several days, don't hesitate to send us a message on Discord - most core developers of Cormas are researchers and sometimes we can be busy with other tasks and simply forget to respond to your PR.