Skip to content

Development

Jump to bottom
Fernando Dodino edited this page Dec 7, 2019 · 56 revisions

Introductory reading

Wollok is being developed on top of XText stack. So, if you are not familiar with it, maybe it would be a good start to take a look at the following links:

Contribution workflow

We use standard open source practices with github. We are using Github projects to handle the issues. To look for an issue to fix, the best thing is looking at the Ready to develop category (avoid the column Rainy day fund / Discuss).

If you don't have access to the repository then

  1. Fork the repository
  2. Create a feature branch for you to work with a descriptive name.
  3. Commit changes and push the new branch to your repo. You may solve feature in Wollok or with native code
  4. Then you should add some tests.
  5. Once you think it is ok and passes all the tests then create a Pull Request (PR) to integrate that branch against our repository's dev branch.
  6. Ask for a reviewer!
  7. Take another issue and start again!!!

... or ask for permissions to fernando.dodino@gmail.com

If you have access to our repository then

  1. Same as above but without the need to fork the repository.
  2. Put the Issue "in progress" and assign it to you, and also set the milestone to the future release.
  3. Still use feature branches with PR.
  4. Once you have created the PR, move the issue to "To Check"

In both cases it is important to refer to the issue in a single commit, and also in the PR, using #number_of_github_issue. For example: fix-#1013-removing-elements-of-collection-during-iteration. This will relate the github issue with the corresponding commit and PR, fostering traceability.

Wollok Design

Wollok Architecture

Since 2020 (Wollok 2.0 I), we have new architecture:

Wollok Development Architecture

This repo contains the Xtext implementation of Wollok Language, which is stored in a different github repository:

  • Wollok Language contains src core libraries, such as lang, lib, game, etc. as well as sanity tests and examples, but is implementation-agnostic
  • Wollok Xtext has the JDK + Xtext implementation of Wollok Language in org.uqbar.project.wollok.lib folder

You must install development environment and run either wollokInstall.sh or wollokInstall.bat script, which will clone recursively Wollok-Language github repository and link the core library files to org.uqbar.project.wollok.lib. Any change you do in lang.wlk, lib.wlk or any core library file, will be directly linked to wollok-language subfolder. You must take into account that you should create two separate PRs for any change involving a language change, and register that change in the CHANGELOG file.

Lifecycle of a change (both Wollok Xtext & language implementations)

Lets say you must add a parameter to a native method of a class in lang.wlk. Expected tasks should be the followings, assuming we are solving issue 2140:

  • Checkout dev branch, pull latest remote changes, create a new branch fix-#2140-adding-parameter-to-foobar
  • Go to lang.wlk file, add parameter in foobar class. This could be done either from wollok-language or org.uqbar.project.wollok.lib, because they are linked together, but we recommend using wollok-language
  • Go to org.uqbar.project.wollok.lib, src/wollok/WFoobar.xtend class and modify native implementation
  • Go to wollok-language and change the tests according to the new expected parameter.
  • Run the sanity tests from Wollok Xtext (you can also run it using wollok-cli from wollok-language folder: WOLLOK_DEV_ROOT=../ wollok test -dontValidate)
  • Change any Xtext tests associated with foobar class
  • Run all the tests, they should end succesfully
  • Open a PR for wollok-language, adding it also to the CHANGELOG file
  • Open a second PR for wollok-xtext
  • Link both PRs

Lifecycle of a change (only xtext implementation)

If a change does not involve a core library file, or it involves a change for the autocomplete, formatter, validator, testing or any other component, then you should'n be aware of wollok-language functionality, resulting in less tasks:

  • Checkout dev branch, pull latest remote changes, create a new branch fix-#2140-validate-wko
  • Modify xtext classes
  • Run all the tests, they should end succesfully
  • Open a PR for wollok-xtext

Lifecycle of a wollok language change

If a change does not involve xtext implementation, then you should create only a wollok-language PR but you should be aware of running sanity tests from Xtext or wollok-cli.

Useful sections (How-To's)

The following pages contain useful information for Wollok developers.

Clone this wiki locally