Rules for code and documentation formatting

Coding Standards

When developing our products, we follow the standard guidelines to writing and documenting code that exist for the specific programming language being used. Please familiarize yourself with the main coding standards of the languages used in the Pip.Services Toolkit and be sure to follow them when developing.

Before creating a pull-request or committing code to a repository, be sure to fully test the code using the standard testing mechanisms available in the programming language you are working with. Tests should cover all developed components and provide enough coverage of the code’s functionality. However, the time it takes for all of the tests to run should not exceed 1-2 minutes.When running and developing tests, it’s necessary to plan a mechanism of safely sending and receiving personal data that might be necessary for the tests (logins, passwords, access keys, etc.). And this information should NEVER end up in the repository!

Documentation Standards

When creating new modules and components, be sure to include a file that contains a detailed description of the created elements. The following sections must be included:

Name and short description
The component’s elements/structure
Descriptions of configuration parameters (if they exist)
A link to the API documentation
Instructions for installing the module

This information should be placed in a README.md file, located at the root of the repository. Use the following two repositories as examples:
https://github.com/pip-services-infrastructure/pip-clients-metrics-dart
https://github.com/pip-services3-go/pip-services3-container-go
‍The written code needs to contain an API description, generated using standard mechanisms for the programming language being used. The API description should be placed in the ‘doc’ or ‘docs’ folder - whichever is standard for the language at hand. This folder should also contain the files describing the configuration and instructions on downloading and installing the product. Follow the link below to see an example:
‍https://github.com/pip-services3-go/pip-services3-elasticsearch-go/tree/master/docs
‍When changing existing products, add a short description of the changes that were made to the CHANGELOG.md file, making sure to indicate the date, version, and author of the changes.For example:

## 1.0.1 - 20/06/2020
- Fixed small issue in Main component

Versioning

Our team keeps to the following versioning strategy:

Major versions don’t support backward compatibility and are placed in a different repository. E.g. Pip.Services Commons 3.0 for Node.js is located in the repository pip-services3-commons-node, whereas version 4.0 of the same component would be located in pip-services4-commons-node
Major versions of a component are included in the namespace. This allows us to use different versions of code in the same project without any naming conflicts.
Minor versions can include new functionality, but backwards compatibility is mandatory. The majority of our users are companies that develop large enterprise systems and backwards compatibility is a must for them! If you need to add breaking changes to a component named ‘Component’, you can create a component named ‘Component2’, and leave the existing component unchanged.
Bug-fix versions only contain fixes and don’t change the existing functionality.
When releasing a new version, the corresponding Git tag is also updated in that repository.
Only the master branch is used. The root of the master branch always contains the latest version.Since the repository is accessible by any user, developers must be very careful and only commit code that has been tested and checked. If developing some new functionality takes a long time, pull requests can be used, but new branches are not created.