How to contribute | Smartcard-based Ticketing Terminal APIs by the Calypso Networks Association

Project governance

CNA’s obviously legitimate to lead the definition of software interfaces to manage Calypso solutions.
Regarding the definition of generic interfaces for the smart card industry, CNA is open to share the driving of this work with any interested organization or manufacturer.

Definition of Calypso layer APIs

The Calypso Networks Association is responsible for specifying, qualifying and promoting the Calypso ticketing standard. Contributions to the definition of Calypso APIs for ticketing terminals are therefore reserved for CNA members participating in the “TC Terminal” technical working group.

Registered members have access to a document database and a discussion forum to exchange ideas, propose and agree on solutions for the design of interoperable Calypso ticketing terminals.
These collaborations have, for example, led to the specification of requirements for the Calypso layer of ticketing terminals. Compliance with these requirements by ticketing terminal solutions ensures interoperability with all Calypso card and SAM products.

Calypso APIs for ticketing terminals:

enable the implementation of libraries that meet the requirements of the Calypso layer,
provide a solution for developing ticketing applications for terminals independently of Calypso middleware solutions,
will soon enable Calypso terminal solutions to certify compliance with Calypso layer requirements.

Join CNA to contribute to defining Calypso APIs for ticketing terminals.

Definition of Reader layer APIs

An interoperable Calypso software layer can only be built on a generic reader software layer interface, independent of card reader solutions and ticketing terminal architecture (embedded/distributed). CNA is not necessarily legitimate in defining such “universal” terminal interfaces for the smart card industry but has initiated these definitions in response to the need for a basis on which to build Calypso APIs.

For the definition of the reader APIs for ticketing terminals, CNA is interested in the participation of any external contributor and is also open to sharing the governance of this project with other entities or the open-source community. (CNA offered the Smart Ticketing Alliance to host this project. Another option currently under consideration is to transfer this responsibility to the Eclipse Keypop open-source project.)

Types of contributions

Thanks for your interest in participating in the reader layer APIs definition for a ticketing terminal. There are several ways to contribute to the project:

Propose a fix for a problem that is already known or that you have identified. In this case you will have to notify the issue in the repository where the problem appeared and reference the issue in all the other repositories affected by the fix.
Propose the creation of a new component: in this case you will first have to create an issue in the repository github.com/calypsonet/calypsonet-terminal-api-website to justify the need and request the creation of a new repository, wait for the issue to be resolved by the decision of the committers, and then create an issue in the new repository signifying the start of development of the new component.

Contributing via fork

Check if there is already a GitHub issue for what you want to work on or create one.
Announce in the comments section that you want to work on the issue. Also describe the solution you want to implement. To improve the chances for your contribution to be accepted, you’ll want to wait for the feedback of the committers.
Fork the repository.
Create a new branch from main for your changes. Name it after the issue number, e.g. #XXX_[description_of_changes].
Implement your changes.
Rebase on main.
Run ./gradlew spotlessApply to format the code and add licence headers to the files.
Run ./gradlew build (to check code formatting and run tests)
Commit your changes using the -s flag in order to add a Signed-off-by footer as mentioned above and use the same email address you are using for your GitHub account.
Use commits messages that respect the commits message conventions.
Push your changes to your forked repository.
Submit a pull request referencing the related issue(s).
After submitting, do not use your branch for any other development, otherwise further changes that you make will be visible in the PR.

Commits message conventions

In order to ensure good readability of the commit history, it is necessary to have consistency in the structure of the commit messages.

Therefore, all contributors to the project are asked to respect the structure of the commits messages as described in the guide Conventional Commits 1.0.0:

<type>[optional scope]: <description>

[optional body]

<footer(s)>

Furthermore, it is requested to indicate in the footer section the associated issue(s) that will be closed (Closes #xxx, closes #yyy, etc...). This will automatically close the associated issue(s) when the pull request is validated (see GitHub Docs for more details).

It is also required to indicate possible references to other associated issues (Refs: #aaa, #bbbb, repository_owner/other_repository_name#ccc, etc...).

Here is fictive example:

feat(observation): allow asynchronous notification of reader events

Add a public method in the observable reader to enable asynchronous notifications.

Closes #34, closes #38
Refs: #12, calypsonet/calypsonet-terminal-reader-uml-api#54