Skip to content

Latest commit

 

History

History
177 lines (117 loc) · 9.57 KB

CONTRIBUTING.adoc

File metadata and controls

177 lines (117 loc) · 9.57 KB

How to contribute

SARL logo

Any contribution to the SARL is welcome. For setting up the development environment of SARL, please follow our recommendations in the following sections.

1. Issues

Issues related to SARL are tracked on GitHub You must use this issue tracker to report and follow your issues.

Additionally, you could have a look on the SARL developers' working plan on Huboard.

In the issue description, provide the following information:

  • Your operating system (and version);

  • The version of SARL you are using;

  • Your language and/or locale (e.g. "en-US");

  • Clear steps to reproduce the bug (including a reduced-case user script, if applicable);

  • Any error messages seen in the Error Console;

  • A description of what you expected to happen;

  • A description of what actually happened;

Note: You can use the wizard in the SARL product for submitting an issue with the technical information already filled. The menu is accessible by selecting the menu SARL > Submit issue to SARL tracker. This wizard required to hae a valid Github account.

2. Guidelines for SARL developpers and contributors

This section describes how to set up the Eclipse development environment for contributing to SARL.

2.1. Tested versions of the development tools

The main SARL developpers are using the following development environment:

  • Java Development Kit (JDK) 17 from OpenJDK or Oracle.

  • Maven 3.9.4 (for shell command-line actions) from Apache.

  • Eclipse 2023-06, for Java and DSL Developers, and for RCP and RAP Developers

2.2. Obtaining the SARL Source Code

We recommend to fork the SARL project into your own Github account, in order to make easier the pull request that is needed for sending your contribution. Forking the SARL project must be done through the Github web interface: click on the Fork button on the SARL project page.

For obtaining the code of SARL, you must clone your fork from Github to your local harddisk:

git clone https://github.com/<your_github_login>/sarl

We recommend to use the git tool on command-line until you’re becoming expert with the git tools that is embedded in Eclipse.

2.3. Structure of the SARL project

The SARL project is splitted into different sub-projects that may be compiled independently. Each project is dedicated to a specific set of features and tools. These sub-projects are:

  • sarl-bom: Provide the Build-of-Material, i.e., a shared list of Maven dependency, for all the SARL sub-projects;

  • sarl-baseutils: Set of Maven artifacts that are independent of SARL but needed to build the SARL artifacts;

  • sarl-lang: Provides the language definition, the associated compiler (including the Maven plugin) and code formatting styles for different text editors;

  • sarl-sdk: Set of Maven artifacts that constitute the SDK for all the SARL developers;

  • sarl-apputils: Shared projects for building applications that are using a SARL compiler;

  • sarl-sre: SARL runtime environment (or SARL virtual machine);

  • sarl-docs: Tools and Doclet for the generation of the documentation, including the API documentation pages;

  • sarl-cli: Set of command-line tools (sarlc, sarldoc, janus…​);

  • sarl-eclipse: Eclipse-based editor for SARL;

  • sarl-officialdoc: Markdown files of the official documentation of SARL.

2.4. First Compilation the SARL Source Code

Maven is the standard tool for compiling SARL.

We recommended to launch the Maven compilation process on the shell command line before importing the code in the Eclipse environment. Indeed, Maven generates several Java code files, and updates resource files with the correct configuration values.

The command line to use (see below) compiles the SARL project and install the Maven modules into your local .m2 repository.

a) Linux or MacOS Operating Systems

In a command-line shell, run the Bash script:

$> ./build-all.sh

b) Windows Operating System

A PowerShell script is provided for building all the projects of SARL:

C:> build-all

2.5. Installing the Eclipse Development Environment

Two different types of contributions could be associated to the SARL project:

  • Contributions to the SARL tool chain (compiler, SDK, etc), excluding Eclipse-based tools; and

  • Contributions to the Ecipse tools: they are the plugins inside Eclipse and the Eclipse IDE.

a) Contributions to the SARL tools excluding Eclipse

For setting up the development environment for contributing to the SARL tools, you should follow the steps:

  • Download the Eclipse IDE for Java and DSL Developers from eclipse.org/downloads/eclipse-packages/. This version of Eclipse includes the Java tools and all the tools for compiling a language grammar.

  • Launch the Eclipse IDE for Java and DSL Developers, and configure it (look&feel, etc.)

  • Import the SARL project: Menu File > Import > Maven > Existing Maven Project

    • CAUTION: We do not recommend to import sarl-bom in Eclipse because of its specific static in the compilation process.

    • Select the folder in which you have cloned the SARL project (see Section 2.2);

    • Click on Finish.

  • Sometimes, the Maven Eclipse Plugin (a.k.a. m2e) does not have its connector installed by default. In this case, errors should appears in the pom.xml files. After displaying the popup window of the error, click on Discover m2e connector and follow the instructions.

  • Clean and compile the project: Menu Project > Clean.

b) Contributions to the Eclipse tools of SARL

For setting up the development environment for contributing to the Eclipse-based tools, you should follow the steps:

  • Download the Eclipse IDE for RCP and RAP Developers from eclipse.org/downloads/eclipse-packages/. This version of Eclipse includes the Java tools and the tools for developping Eclipse plugins and applications.

  • Launch the Eclipse IDE for RCP and RAP Developers, and configure it (look&feel, etc.)

  • Import the SARL project: Menu File > Import > Maven > Existing Maven Project

    • CAUTION: We do not recommend to import sarl-bom in Eclipse because of its specific static in the compilation process.

    • Select the folder in which you have cloned the SARL project (see Section 2.2);

    • Click on Finish.

  • Set the Eclipse target platform, i.e. the definition of the Eclipse plugins to be imported by the project.

    • Open the target platform file sarl-target-platform.target in the project sarl-eclipse;

    • Wait for all the entries in the target file to be refreshed, i.e each location must contains the list of the features to be imported;

    • Click on Set as Target Platform or Reload Target Platform at the upper right corner of the file editor.

  • Sometimes, the Maven Eclipse Plugin (a.k.a. m2e) does not have its connector installed by default. In this case, errors should appears in the pom.xml files. After displaying the popup window of the error, click on Discover m2e connector and follow the instructions.

  • Clean and compile the project: Menu Project > Clean.

2.6. Creating the launch configuration within Eclipse

To create the initial version of the launch configuration, open the product overview and click in the top right corner on the "Launch an eclipse application" Button. This will automatically create a first launch configuration.

Then,the "Run Configuration" to manage the detail of your launch config, switch to the "Plug-ins" tab, and check the "Include required Features and Plug-ins automatically while launching" checkbox, and run it.

2.7. Compilation of SARL before Submitting your Contribution

Prior to any sending of your contribution (see Section 2.5), you must ensure that your local copy of SARL compiles without error.

The best and "sure" way to proceed is to use Maven on the command line, because it is the tool used by our compilation server for validating your contribution.

Type on the command-line:

mvn clean install

This command line will launch the compilation, checkstyle and unit tests. It must be successfull.

2.8. Sending the Contribution

For sending your contribution to the SARL master repository, you must request a pull (PR) to the GitHub repository.

For being merged, your must ensure the following points:

  • Your PR must be compilable with Maven.

  • Your PR must pass the compilation process successfully, including the code compilation, unit tests, and code style checking.

  • You must sign the Contributor License Agreement on GitHub. It is supported by cla-assistant (CLA text).

  • Your PR should be reviewed by one or more of the main contributors for ensuring it is following the development rules and philosophy related to SARL.

The page of your PR on Github is displaying the status of your PR. If one point is failing, please follows the steps:

  • Go on the CI console for obtaining the cause of the failure.

  • Fix the code of your PR on your local copy.

  • Commit on your local repository, compile, and test until you have fixed the issue.

  • Push the changes on the same PR with git push -f, i.e. the same Git repository as the one used for the PR. Do not create a new PR for the fix.

  • The GitHub platform will relaunch the CI process automatically.