thermondo Developer Handbook
thermondo would not exist without open source and free software. Almost our entire stack is based upon open source tools and libraries and all platforms we build upon have a strong relationship with open source and free software.
We believe that no matter how much you give to the community you will always receive more. This is why we try to contribute as much as possible.
When do I open source software I build at thermondo?
You should always open source the tools you are developing at thermondo. It should be your initial thought to do that and how to publish your work.
With that being said, there are some constraints or rather things or information you should NOT publish:
You should act at thermondo’s best interest. If you are uncertain or feel insecure, simply approach your team lead.
When creating a new repository make sure to initialize it with the correct
.gitignore file and License. Next make sure to add a repository
description and tags to classify your work. Optionally you can add a website,
which can be a link to the documentation, package index or github.io page.
Make sure to protect your master branch. No one should be able to force push to your main branch. Users need to be able to rely on your commit history.
Please also enable mandatory peer reviews. Nothing should be merged without review.
All code at thermondo has to have tests, that applies double for public code. A coverage over 90% is required but a coverage of 100% is preferable.
Please make sure to enable Codecov for your test suite.
Furthermore make sure to document how to invoke or write tests. You can use tools like tox to simplify usage.
Make sure to add static code linters to your CI process. It will provide contributors with instant feedback and guidance and will allow them to make pull requests with confidence.
Please ask your team lead to enable restricted GitHub extensions for your repository if needed.
We previously used Travis for continuous integration, but you can set up a CI pipeline in GitHub Actions going forward. Check out the GitHub Actions docs if you are unfamiliar with it.
A good open source tool is only as good as its documentation. Make sure to add
a detailed documentation with examples. Depending on the size of your package it
might be a good idea to go for a hosted documentation using
ReadTheDocs or GitHub pages.
For really small packages or tools, a simple README file might just do.
Make sure to spell check your documentation.
Furthermore it’s recommended to use tools like Sphinx to document within your code base. This makes keeping documentation up to date easier for contributors.
All repositories should have a contributing guide. To keep things simple you can link to our development guidelines.
We use the Apache License 2.0. It is preferable to the MIT or BSD license because it has a better protection against patent trolls or any other legal action against thermondo.
License Template:
Copyright [yyyy] thermondo GmbH
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Maintaining a separate changelog file can be harder for contributors. Instead we recommend to simply add a link to your GitHub release page in that file. Please make sure to always tag new releases and to add a good description about the changes included in the tag.
The easiest way to release a new version is to use hub. For example:
hub release create origin 2.1.5
Example tag message:
2.1.5
* Fix #123 -- Fix documentation typo
* Fix #132 -- Fix Windows compatibility issue
This will automatically create a signed tag and a release with release message.
The release message is also picked up by bots like PyUp and requires.io.
We recommend using Semantic Versioning since it is widely used and most intuitive for users. There are cases though, where other version number formats might make sense.
If applicable, publish new versions of your work as a part of your continuous integration pipeline. For example, you can use GitHub Actions to publish Python packages to PyPI. If your project is a running application, you may choose to set up Heroku to monitor your repository and redeploy when it detects a successful CI run.