Contribute

    On this page

      Report bugs or request features

      The easiest way to contribute to Comunica is by reporting the bugs your encounter, and requesting new features or enchancements.

      Both of these should be done via GitHub issues. Make sure to be as descriptive as possible, and completely fill in the requested template.

      Fix bugs or implement new features

      If there is a certain bug that annoys you, or if you see the opportunity for a new feature that would make your life easier, you are welcome to contribute by submitting a pull request. Before you open a pull request, it is considered a good practise to first open an issue or discuss it with the community.

      Don't know on what to get started? Have a look at issues tagged with the good-first-issue label or the dev-ready label. Issues tagged with good-first-issue are issues that should be implementable by new contributors. Issues tagged with dev-ready are potentially harder issues, but they are directly implementable without research.

      When contributing, make sure to keep in mind the following:

      Tips and tricks:

      • Only do yarn install in the repo root, and never in one of the sub-packages, as this can break your repo.
      • yarn run build will (re)build all TypeScript to JavaScript. This can also be executed on package-level.
      • yarn run build-watch will continuously build the TypeScript to JavaScript. This is useful during development.
      • yarn test and yarn run lint execute the tests and linter checks locally. Before a PR is opened, these must always pass, and testing coverage must be 100%.
      • When editing configuration files in packages like actor-init-sparql, yarn run prepare can be executed to compile the JSON files to JavaScript before they can be executed. (not needed when executing dynamically)
      • When modifying a dependency package such as sparqlee, Yarn's link functionality can be used to force your local version of that dependency to be used in Comunica.

      Write documentation

      This website aims to provide detailed documentation on how to use and modify Comunica. If you see an opportunity for improving this documentation, fixing mistakes, or adding new guides, you are welcome to contribute via GitHub.

      Create example code

      The Comunica examples repository contains several example packages that modify Comunica, with details on how they are created and how they work. Anyone is more than welcome to contribute new example packages to this repository. For inspiration, you can have a look at the example requests.

      Guidelines for core developers

      The following guidelines only apply to people with push access to the Comunica repositories.

      Branching Strategy

      The master branch is the main development branch.

      Releases are tags on the master branch.

      All changes (features and bugfixes) must be done in a separate branch, and PR'd to master.

      Recursive features must be PR'd to their parent feature branches, as a feature can consist of multiple smaller features.

      The naming strategy of branches is as follows:

      • Features: feature/short-name-of-feature
      • Bugfixes: fix/short-name-of-fix

      Issue Strategy

      Issues should be assigned to people when possible, and must be progressed using the applicable GitHub project boards:

      General issues progress:

      1. To Do: When the issue is accepted and assigned, but not in progress yet.
      2. In Progress: When the issue is being worked on by the assignee.
      3. To Review: When the issue is resolved, but must be reviewed. This can be attached to a PR.
      4. Done: When the issue is resolved and reviewed. If attached to a PR, this can be merged, or closed otherwise.

      Making a new release

      Making a new release only requires invoking yarn run publish-release from the repository root, which does the following using lerna:

      • Prompts your for providing the new version (major, minor, patch).
      • Bump the versions from all changed packages.
      • Generate a changelog from all commits since the last release. The process will halt until you modify (and save) the changelog where needed (remove unneeded commits, and categorize them), and confirm by pressing any key in the console.
      • Release all changed packages to npm.
      • Push the tag to GitHub.
      • Push to master.

      Making a new pre-release

      Making a new release only requires invoking yarn run publish-canary from the repository root, which does the following using lerna:

      • Temporarily do a patch release increment on all packages in the form of <version>-alpha.<git-head-sha>.0.
      • Release all packages to npm with the next tag.
      • Undo temporary changes

      Pre-releases do not trigger changelog changes, git commits, and pushes.