Skip to content

Contributing to MapStore

Jump to bottom
Tobia Di Pisa edited this page Nov 11, 2024 · 16 revisions

Contributing to MapStore

Getting Involved

There are several ways you can contribute to MapStore development. If you are a developer, you can provide new features and bug fixes, by using pull requests. But you can also help by:

Reporting Bugs

Before reporting a bug on the project's issues page, first make sure that your issue is caused by MapStore, not your application code (e.g. passing incorrect arguments to methods, etc.). Second, search the already reported issues for similar cases, and if it's already reported, just add any additional details in the comments.

After you've made sure that you've found a new MapStore bug, here are some tips for creating a helpful report that will make fixing it much easier and quicker:

  • Write a descriptive, specific title. Bad: Map does not show. Good: Doing X in Chrome causes Z.
  • Include browser, OS and MapStore version info in the description.
  • Create a simple test case that demonstrates the bug (e.g. using JSFiddle or JS Bin).
  • Check whether the bug can be reproduced in other browsers.
  • Check if the bug occurs in the stable version, master, or both.
  • Bonus tip: if the bug only appears in the master version but the stable version is fine, use git bisect to find the exact commit that introduced the bug.

If you just want some help with your project, try asking on the MapStore users mailing list instead.

Contributing Code

The information below will cover the process to contributing code to MapStore. Obviously the process for small contributions is going to be more agile that the process for large contributions. In any case, signing a contributor license agreement is required to provide contributions.

Proposing small contributions

For a small change to a handful source files a project committer can review and apply the change on your behalf. This is a quick workaround allowing us to correct spelling mistakes in the documentation, clarify a javadoc, or accept a very small fix. We understand that fixing a single source file may require changes to several test case files to verify the fix addresses its intended problem.

While we happily accept patches, we're also committed to quality. So bugfixes, performance optimizations and small improvements that don't add a lot of code are much more likely to get accepted quickly.

Before sending a pull request with a new feature, check if it's been discussed before already (either on GitHub issues or on the MapStore developers mailing list), and ask yourself two questions:

  1. Are you sure that this new feature is important enough to justify its presence in the MapStore core? Or will it look better as a plugin in a separate repository?
  2. Is it written in a simple, concise way that doesn't add bulk to the codebase?

If your feature did get merged into master, please consider submitting another pull request with the corresponding documentation update.

Proposing Large Contributions: the role of MapStore Improvement Proposals

If someone is thinking to propose a change to MapStore that is particularly destabilizing or far-reaching, a MapStore Improvement Proposal (MIP) is required. MIP are tracked github issues and provide an opportunity for PSC members and users alike to provide feedback about the design of a proposed feature or architectural change. The proposal should be iteratively edited in response to community feedback.

To upgrade an issue to a MIP, an active PSC memeber should give the ticket the 'MIP' label in the issue tracker, and announce the issue on the developer mailing list. If a ticket has a MIP label, its resulting work can't be committed unless it also has the 'Approved' label. To be approved, it must pass community vote (see below). When a MIP is announced, PSC members should review and provide feedback in the issue comments.

If a user would like to submit a MIP, they are welcome to write it as a ticket but should find an active PSC member willing to promote it to MIP status.

The voting process works as follows:

  1. Proposals may be made by any interested party (PSC, Non-PSC, committer,user,etc…). All community members are encouraged to review proposals, and provide their support and feedback.
  2. Each PSC member may vote one of the following in support of the proposal:
  • +1 : For
  • +0: Mildly for, but mostly indifferent
  • -0: Mildly against, but mostly indifferent
  • -1 : Against, accompanied with a detailed reason of being against
  1. Voting remains open for ten days or until all PSC members have cast their vote.

  • At the end of ten days time any remaining votes are assumed to be +0.

  • Any active PSC member can during ten days request an extension of voting for an additional ten days; the voting period can only be extended once.

  • Any PSC member who votes “-1” against a proposal must provide a reasonable explanation as to why.

  • Any PSC member who votes “-1” against a proposal has a limited time to provide constructive feedback as to how their -1 vote can be addressed.

    The GSIP author must incorporate any reasonable feedback into the proposal.

    The PSC member who voted “-1” must consider whether their feedback has been addressed and whether they wish to change their vote.

  1. Voting results:

  • A vote of “+1” means support for a proposal

  • The neutral votes “+0”, “0”, and “-0” all count the same as “0” but permit PSC members to indicate a slight tendency for, neutral, or against a proposal respectively

  • A vote of “-1” means opposition to the proposal

    A unanimous response is:

  • Successful: No -1 votes against it, or

  • Unsuccessful: No +1 votes for it.

  1. A GSIP is accepted if it receives:
  • at least 30% “+1” votes, and
  • no “-1” votes (or all feedback from any “-1” votes has been addressed and any “-1” voters have changed their votes)
  1. In the event of an successful non unanimous vote, the following steps are taken:
  • Each member who votes -1 may supply an alternative with which the original author can use to rework the proposal in order to satisfy that PSC member.
  • If at least one -1 voting PSC member supplies some alternative criteria, the original author must rework the proposal and resubmit, and the voting * process starts again from scratch.
  • If no -1 voters are able to supply alternative criteria, the proposal is accepted.
  1. In the event of an unsuccessful vote, the author may choose to rework and submit. A proposal may not be resubmitted after being rejected three times.

Recommendations for contributing code changes to MapStore source

Making Changes to MapStore Source

If you're not yet familiar with the way GitHub works (forking, pull requests, etc.), be sure to check out the awesome article about forking on the GitHub Help website — it will get you started quickly.

You should always write each batch of changes (feature, bugfix, etc.) in its own topic branch. Please do not commit to the master branch, or your unrelated changes will go into the same pull request.

Pull request guidelines

Your pull request must:

  • Follow MapStore's coding style.

  • Pass the integration tests run automatically by the Github Action - Continuous Integration system.

  • Address a single issue or add a single item of functionality. (Start the pull request title with the addressed issues if in case and #NUMBER_OF_ISSUE)

  • Contain a clean history of small, incremental, logically separate commits, with no merge commits.

  • Use clear commit messages.

  • Be possible to merge automatically.

The test and lint build targets

It is strongly recommended that you run

npm test
npm run lint

before every commit. This will catch many problems quickly, and it is much faster than waiting for the CI integration tests to run.

The test build target runs a number of quick tests on your code.

The lint build target runs ESLint checks on your code.

File Naming Conventions

The test files should in a folder named __tests__ in the module folder.

If you are testing a specific component follow the following convention:

  • Component: MyComponent.jsx
  • Test File: MyComponent-test.jsx

Follow MapStore's coding style

MapStore follows a strict coding style, enforced by ESLint rules.

The set of used rules can be found in the ESLint config package eslint-config-mapstore file, deployed on npm and configured in the package.json.

Additionally if you use VScode these are the extensions to install that will help notify lint errors on the fly

We suggest also to add the following configuration that will fix lint errors while saving the file (.vscode/settings.json)

"editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
},

You can run the linter locally on your machine before committing using the lint target:

npm run lint

In addition, take care of adding the standard file header in each javascript / css added file, and update copyright years in modified ones.

This is the standard file header:

/**
 * Copyright <year>, GeoSolutions Srl.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree.
 */

Configure your editor

If possible, configure your editor to follow the coding conventions of the library. A .editorconfig file is included at the root of the repository that can be used to configure whitespace and charset handling in your editor. See that file for a description of the conventions. The EditorConfig site links to plugins for various editors.

Pass the integration tests run automatically by the CI system

The integration tests contain a number of automated checks to ensure that the code follows the MapStore style and does not break tests or examples. You can run the integration tests locally using the test target:

npm test

Address a single issue or add a single item of functionality

Please submit separate pull requests for separate issues. This allows each to be reviewed on its own merits.

Contain a clean history of small, incremental, logically separate commits, with no merge commits

The commit history explains to the reviewer the series of modifications to the code that you have made and breaks the overall contribution into a series of easily-understandable chunks. Any individual commit should not add more than one new class or one new function. Do not submit commits that change thousands of lines or that contain more than one distinct logical change. Trivial commits, e.g. to fix lint errors, should be merged into the commit that introduced the error. See the Atomic Commit Convention on Wikipedia for more detail.

git apply --patch and git rebase can help you create a clean commit history. Reviewboard.org and Pro GIT have explain how to use them.

Use clear commit messages

Commit messages should be short, begin with a verb in the imperative, and contain no trailing punctuation. We follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html for the formatting of commit messages.

Git commit message should look like:

Header line: explaining the commit in one line

Body of commit message is a few lines of text, explaining things
in more detail, possibly giving some background about the issue
being fixed, etc etc.

The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
74 characters or so. That way "git log" will show things
nicely even when it's indented.

Further paragraphs come after blank lines.

Please keep the header line short, no more than 50 characters.

Be possible to merge automatically

Occasionally other changes to master might mean that your pull request cannot be merged automatically. In this case you may need to merge your branch with more recent master, resolve any conflicts, and git push to update your branch so that it can be merged automatically. Please try to not rewrite the history of a pull request after the first review or it will be very hard for the reviewer to see if the required changes has been applied, expecially for big pull requests.

Improving Documentation

All MapStore objects (i.e. components, plugins, actions, reducers etc) should be properly documented in their JS documentation, please follow the required JSDoc syntax looking at the online documentation available in the JSDoc web site for more details.

Thank you for every contribution that helps to keep updated the MapStore's documentation.

Contributor License Agreement

A Contributor License Agreement (CLA) is a common and beneficial practice for projects like MapStore. By having contributors sign a CLA, it ensures that all contributions are legally permitted and that contributors give permission for the project maintainers to use, modify, and distribute their contributions. This helps protect the project from future legal issues and provides clarity on the ownership of the code, which is important if we decided to start the process of becoming an OSGEO project. The current WIP for a CLA is available here.

Thank You

At the end, however you decide to contribute to the project, your help is very welcome and we would like to thank you for doing it.

Clone this wiki locally