logo Contributing

See the guidelines below before contributing to the INTERSECT SDK project.

Branches and merge requests

We will have different branching strategies depending on the type of repository we're dealing with.

Merge requests should have at least one other person approve it before merging it in to the unification branch; please remember to tag any relevant people as Reviewers through Gitlab. In every merge request, the current branch should be created from and target the same branch.

Microservices, adapters, digital twins, and UI

We currently have two "primary" branches for each repository: next and main. Developers will want to create feature branches off of next and target next with merge requests. We will have a development server representing each branch.

The next branch represents the latest branch we target before merging into production level code. We'll have an associated development server with internally accessible endpoints; feel free to plug in to any of these endpoints for development work to save you from having to spin up some of the services. We do not want to guarantee that this deployment will always be working, so feel free to use these endpoints as you like.

We use the main branch to represent our latest production-level code. We'll occasionally try to merge hotfixes into main, but otherwise only the next branch should be merged into main. Some endpoints (such as databases) will never be exposed to users for development. In some cases (i.e. demos), we would ask you NOT to actively develop using these endpoints.

To get the latest URLs to each deployed service, please see the Environments section.

Libraries

NOTE: We are currently working out the appropriate branching plan for libraries, so this information is subject to change.

Instead of utilizing next and main, we will tag our branches utilizing semantic versioning. Specifically - branches with different major versions should be assumed to have separate lifecycles once created, and should not be merged into one another.

Since major versions imply removing backwards compatibility, it makes sense to create branches from the latest major version you're targeting. Since minor and bugfix patches should not break backwards compatibility, it makes sense to only maintain the latest minor/bugfix version as a branch, and try to coordinate version bumping as a unified process. However, we should presume that every version released will have a Git tag associated with it.

As an example, consider the following branch layout:

  • 1 - previous major version which is not accepting new features, but is accepting bugfixes (protected branch)
  • 1 - fix infinite loop - bugfix targeting major version 1
  • 2 - current major version (protected branch)
  • 2 - fix infinite loop - bugfix targeting major verions 2
  • 2.1 - next planned minor version for major version 2
  • 2.1 - add feature A - feature branch targeting branch 2.1
  • 2.1 - add feature B - feature branch targeting branch 2.1

We should assume that protected branches will live forever, and non-protected branches will eventually be deleted. In this case, the development cycles would occur like this:

  • 1 - fix infinite loop will eventually be merged into 1 and deleted. (If this is the only bugfix branch, this merge request would include a bumping of the bugfix version.)
  • 2 - fix infinite loop will eventually be merged into 2 and then deleted.
  • 2.1 - add feature A and 2.1 - add feature B will be created from and target branch 2.1.
  • After all feature branches derived from 2.1 have been merged into 2.1, 2.1 will bump its version, then be merged into 2 and deleted.

Note that it doesn't really matter whether or not 2 - fix infinite loop gets merged into 2 before 2.1 or not. If 2.1 gets merged first, followed by the bugfix branch, the final tag would be 2.1.1; if the bugfix branch gets merged first, the final tag would be 2.0.0.

DevOps

DevOps repositories will only have a single main branch. Feature branches should be created from main, and merge requests should target main.

We will not be maintaining any extensible Terraform modules in this group, so we shouldn't need to worry about git tagging.

Python development

This section discusses linters, formatters, and style guides for the Python INTERSECT-SDK.

Linting

Use the flake8 linter tool when writing Python code. Instructions for setting up flake8 with Visual Studio Code are available here. Instructions for setting up flake8 with Sublime Text are available here for the LSP-pylsp package.

Formatting

Use the Black formatter for Python code. Instructions for using this formatter with Visual Studio Code are available here. Instructions for using the formatter with Sublime Text are available here for the LSP-pylsp package.

Docstrings

Docstrings for Python classes, functions, and modules should adhere to the Google style. The docstrings are processed by the napoleon Sphinx extension for the INTERSECT-SDK documentation. See here for more information.

C++ development

This section discusses linters, formatters, and style guides for the C++ INTERSECT-SDK.

Coming soon...

Copyright © 2023 INTERSECT