CONTRIBUTING.md

Contributing to Circles

🐐 Welcome!

We are very excited to hear that you take your time to help building the Circles UBI project used by users and groups all around the world! ⭐ If you have an idea, suggestion or bugfix to improve Circles, please read these guidelines carefully and reach out for help in our channels when you have any questions.

🐒 Code of Conduct

Note: Circles is a community project maintained by volunteers and people dedicated to it in various organizational forms. While we are working hard to improve the infrastructure, stability and code, please be respectful with the current contributors around this project which dedicate their limited time to make all of this work. ❤️

To create a safe environment for all contributors and members, Circles is governed by the Circles Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to counsellor@bitspossessed.org.

🐠 Join us, ask for help

We have an official board and chat where the community helps you if you have questions:

➡️ Official Circles chat @ RocketChat

• Say hi and tell the others about yourself in our #general channel
• Check out the #development channel for technical questions

➡️ Official discussion forum for Circles @ Discourse

🐮 Overview

If you are new to the Circles project and you need an overview of all components of the system and some development guidelines, we recommend you to check out the following documents:

• The official Circles Handbook gives you an introduction into the Circles system architecture, tutorials to deploy your own Circles server but also how to write and run Circles code locally on your computer
• The Circles Whitepaper will give you a good overview of how Circles actually works
• Check out the FAQ on the Circles website

🐼 How Can I Contribute?

Any sort of contribution is welcome! Here are some examples:

• Report a bug you identified
• Write code which enhances the system or fixes an issue
• Add a tutorial to the Circles Handbook
• Improve the documentation or installation steps for a service
• Translate the Circles Wallet or Website in another language

Reporting Bugs

This section guides you through submitting a bug report for Circles in a GitHub issue. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻, and find related reports 🔎.

Before creating bug reports, please check if the problem has already been mentioned in the regarding issues of the regarding GitHub repository. You can also get some help from the Circles developer community to determine for example the suitable repository to create your issue. When you are creating a bug report fill out the required bug report template including as many details as possible.

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

Suggesting new features

This section guides you through submitting an enhancement suggestion for Circles, including completely new features and minor improvements to existing functionality.

Before suggesting a new feature on GitHub you can introduce your ideas first to the Circles community by writing a post in the Circles forum. You might receive helpful feedback before implementing your idea. After you've determined which repository your enhancement suggestion is related to, create an issue on that repository using the feature template.

Your First Code Contribution

Unsure where to begin contributing to Circles? You can start by looking through these good-first-issue or help-wanted issues:

• good-first-issue - issues which should only require a few lines of code, and a test or two
• help-wanted - issues which should be a bit more involved than good-first-issue issues

🦥 Styleguide

Code

• All repositories have linters in place which help you to follow the recommended style guidelines for formatting code. Read in the according README.md of the repository to find out how to run the linter tasks.

Commit Messages

• Capitalize the first line and each paragraph
• Use present tense ("Add feature ..." instead of "Added feature ...")
• Use the imperative mood ("Move cursor to ..." instead of "Moves cursor to ...")
• Limit the first line to 72 characters or less
• Do not end the subject line with a period
• Use the body to explain what and why you have done something, refer to issues and PRs if you want

Check out the guidelines for commit messages for more examples and recommendations.

Branches

• Follow a simple naming scheme clearly describing the topic (e.g., refactor-authentication, make-retina-avatars) you are working on

Pull Requests

• Use the description field to describe what you are introducing or changing in your branch
• You can add TODO lists in the description field
• Mention related issues in the description field by writing Closes #<issue no>. This will automatically close the issue when your contribution got merged

🐢 How to ..

Merge branches

• You can not push directly to main, please create a branch with your changes and open a PR to request code review before merging
• Change the PR to "Draft" state if your work is not done yet
• Make sure you followed the Styleguide and linter recommendations
• Verify that all status checks are passing
• Click "Ready to Review" to request merging your branch into main
• Merges require the approval of at least one core maintainer. The reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be finally accepted

Release new versions

• All releases follow the semantic versioning scheme
• The main branch should contain only tested, reviewed and released code
• Release additions, updates, fixes and breaking changes are always documented in CHANGELOG.md following this scheme
• Release commits are tagged via git and additionally maintained as GitHub releases