This document describes the guidelines to contribute to the Scorpio NGSI-LD Broker. If you are planning to contribute to the code you should read this document and get familiar with its content.
If you are interested to make any contribution to the ScorpioBroker, please download the contributor license agreement listed below and send us you signed agreement via email scorpio-support@listserv.neclab.eu
ScorpioBroker Entity Contributor License Agreement
ScorpioBroker Individual Contributor License Agreement
Before we get started, here are a few things we expect from you (and that you should expect from others):
- Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct.
- Please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution.
- When adding content, please consider if it is widely valuable. Please don't add references or links to things you or your employer have created as others will do so if they appreciate it.
- When reporting a vulnerability on the software, please, put in contact with Scorpio repo maintainers in order to discuss it in a private way.
- Scorpio Brokers programming language is Java and it uses Postgres and Postgis specific SQL queries.
- Scorpio uses Maven as dependency management and build system. More details in our dependency guidelines
- Some tools we provide are written in Python. These tools should try to follow best practices as well. However we are well aware that the "Pythonic way" and Java best practices do not always match up so we are not as strict here.
- Generaly we try to stay in line with Java Best Practices when there is no GOOD reason to not. We are aware that there is some best practices which are a matter discussion in the community. This can always be discussed in a PR.
- Common sense efficientiancy in the code is expected. (E.g. multiple loops through the same structure is not acceptable)
- Simple code (i.e. cleaner and shorter) is preferred upon complex code. However there is always a trade off between performance and maintainability. Our guideline here comes in form of an Einstein quote: “Everything should be made as simple as possible, but no simpler.”
- Code contributed to Scorpio must follow the code style guidelines in order to set a common programming style for all developers working on the code.
Note that contribution workflows themselves (e.g. pull requests, etc.) are described in another document (FIWARE Contribution Requirements).
If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question.
If you don't see your idea listed, and you think it fits into the goals of this guide, do one of the following:
- If your contribution is minor, such as a typo fix, open a pull request.
- If your contribution is major, such as a new guide, start by opening an issue first. That way, other people can weigh in on the discussion before you do any work.
As explained in (FIWARE Contribution Requirements) contributions are done using a pull request (PR). The detailed "protocol" used in such PR is described below:
- Direct commits to master branch (even single-line modifications) are not allowed. Every modification has to come as a PR
- In case the PR is implementing/fixing a numbered issue, the issue number has to be referenced in the body of the PR at creation time
- Anybody is welcome to provide comments to the PR (either direct comments or using the review feature offered by Github)
- Use code line comments instead of general comments, for traceability reasons (see comments lifecycle below)
- Comments lifecycle
- Comment is created, initiating a comment thread
- New comments can be added as responses to the original one, starting a discussion
- After discussion, the comment thread ends in one of the following ways:
Fixed in <commit hash>in case the discussion involves a fix in the PR branch (which commit hash is included as reference)NTC, if finally nothing needs to be done (NTC = Nothing To Change)
- PR can be merged when the following conditions are met:
- All comment threads are closed
- All the participants in the discussion have provided a
LGTMgeneral comment (LGTM = Looks good to me)
- Self-merging is not allowed (except in rare and justified circumstances)
Some additional remarks to take into account when contributing with new PRs:
- PR must include not only code contributions, but their corresponding pieces of documentation (new or modifications to existing one) and tests
- PR modifications must pass full regression based on existing test (unit, functional, memory, e2e) in addition to whichever new test added due to the new functionality
- PR should be of an appropriated size that makes review achievable. Too large PRs could be closed with a "please, redo the work in smaller pieces" without any further discussing
Discussions about the Open Source Guides take place on this repository's Issues and Pull Requests sections. Anybody is welcome to join these conversations.
Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation.
- ALL dependency must be done through Maven only. All dependencies MUST be available on a public Maven repositories.
- We are only accepting new depencies which are released under a well recognized OSS license
- Scorpio only relies on the Central Maven Repository at the moment. New repositories MUST be added in the corresponding pom.xml. .m2 configs are not acceptable.
- We will NOT accept any contribution that includes binary files
- We are not using any platform dependent depdencies at the moment. If any platform based depdencies are introduced the following points must be met.
- Maven profiles MUST be used to control the dependencies.
- Profiles MUST include an activation based on the platform. So that a default build on the host OS just works as default. Maven profiles
- Support for Windows and Linux 64Bit is a MUST. 32Bit support is a SHOULD as 32Bit is coming to an end.
- Linux ARM64 is considered a SHOULD at the moment but might become a MUST. Linux ARM hf is a weak SHOULD.
- Support for Mac is considered a SHOULD as we recognize that testing on Mac OS/OS X is legally not possible without buying a Mac.
- All dependencies MUST work relatively out of the box with the standard build. Relatively means e.g.
- We will not accept something which requires an installation/compilation manual.
- An apt-get on Linux is fine as this is the common way in Linux. BEST is that the native library is packaged with the Java dependency.
- If there is a platform specific optimization or something similar (e.g. hardware optimized libraries), it of course only has to be provided for that platform.
- Scorpio uses Maven as build tool. All contributions MUST follow the file structure dictated by Maven.
- Additional resources like config files MUST be provided in the resources folder.
Note that currently not of all existing Scorpio code base conforms to these rules. There are some parts of the code that were written before the guidelines were established. However, all new code contributions MUST follow these rules and, eventually, old code will be modified to conform to the guidelines.
- There shall be NO compiler warnings. Code needs to be clean. If you have a warning that you consciously want to ignore use the @ignorewarning annotation and comment it.
- Public methods shall always have comments and javadoc
- A Logger shall always be used. NO system.out.println()
- Exceptions shall always be handled. Empty catch blocks are not acceptable. If nothing can be done log the error.
- Avoid commits that only change the formatting of a file.
All .java files MUST contain the following copyright header
/*
* Scorpio Broker
*
* file: FILE NAME
*
* Authors: The Scorpio Development Team (scorpiobroker@neclab.eu)
*
*
* NEC Laboratories Europe GmbH --- PROPRIETARY INFORMATION
*
* The software and its source code contain valuable trade secrets and shall be maintained in
* confidence and treated as confidential information. The software may only be used for evaluation
* and/or testing purposes, unless otherwise explicitly stated in the terms of a license agreement or
* nondisclosure agreement with NEC Laboratories Europe GmbH.
* Any unauthorized publication, transfer to third parties or duplication of the object or source code –
* either totally or in part - is strictly prohibited.
* Copyright (c) 2021 NEC Laboratories Europe GmbH All Rights Reserved.
*
* NEC Laboratories Europe GmbH DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY
* AND FITNESS FOR A PARTICULAR PURPOSE AND THE WARRANTY AGAINST LATENT
* DEFECTS, WITH RESPECT TO THE PROGRAM AND THE ACCOMPANYING
* DOCUMENTATION.
*
* NO LIABILITIES FOR CONSEQUENTIAL DAMAGES:
* IN NO EVENT SHALL NEC Laboratories Europe GmbH or ANY OF ITS SUBSIDIARIES BE
* LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES
* FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF INFORMATION, OR
* OTHER PECUNIARY LOSS AND INDIRECT, CONSEQUENTIAL, INCIDENTAL,
* ECONOMIC OR PUNITIVE DAMAGES) ARISING OUT OF THE USE OF OR INABILITY
* TO USE THIS PROGRAM, EVEN IF NEC Laboratories Europe GmbH HAS BEEN ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGES.
*
* THIS HEADER MAY NOT BE EXTRACTED OR MODIFIED IN ANY WAY.
*/
- Stick to the Java best practices.
Most Scorpio devs use Eclipse with the default auto format settings for Java. It would be highly appreciated to stick to those. We extracted the settings below We will not reject any PR because of different formatting. However we will reject bad formatting. As an example we have no stakes in the "new line before { or not" discussion. But we will reject endless lines.