Skip to content
OTOBO Community Guide

Contributing to the OTOBO Open Source Project

OTOBO is open source under the GitHub organization RotherOSS (https://github.com/RotherOSS/otobo). If you want to report bugs or contribute your own code, follow this workflow:

1. GitHub Workflow

Section titled “1. GitHub Workflow”

1.1 Fork & Clone

Section titled “1.1 Fork & Clone”
  1. Create a fork of https://github.com/RotherOSS/otobo.
  2. Clone your fork locally:
    Terminal window
    git clone https://github.com/<your-user>/otobo.git
    cd otobo

1.2 Branching

Section titled “1.2 Branching”

Create a new branch for every change:

Terminal window
git checkout -b feature/<short-description>

Example:

Terminal window
git checkout -b feature/add-hello-world-module

1.3 Commit & Push

Section titled “1.3 Commit & Push”

  1. Implement your code.

  2. Add meaningful commit messages:

    Terminal window
    git add .
    git commit -m "Adds HelloWorld module with basic functionality"

  3. Push your branch:

    Terminal window
    git push origin feature/add-hello-world-module

1.4 Pull Request

Section titled “1.4 Pull Request”
  1. Open your fork on GitHub.
  2. Click on Compare & pull request.
  3. Briefly describe in the PR text what your feature/bugfix does and why it is important.
  4. Select the correct target branch (usually master or development).

2. Code Style & Tests

Section titled “2. Code Style & Tests”

2.1 CodePolicy

Section titled “2.1 CodePolicy”

RotherOSS uses the tool CodePolicy (https://github.com/RotherOSS/CodePolicy) to check coding standards.

  • Installation:

    Terminal window
    cpanm CodePolicy

  • Execute in the repo root:

    Terminal window
    CodePolicy --check .

2.2 Perl Modules & POD

Section titled “2.2 Perl Modules & POD”
  • Every Kernel::System::* and Kernel::Modules::* module must contain POD documentation.
  • Declare dependencies in our @ObjectDependencies.
  • Ensure you use use strict; use warnings;.

2.3 Unit Tests

Section titled “2.3 Unit Tests”

OTOBO uses Mojolicious tests and [Test::More]. Place your tests in t/:

Terminal window
prove -l t/MyModule.t

3. Issue Management & Reviews

Section titled “3. Issue Management & Reviews”

3.1 Opening Issues

Section titled “3.1 Opening Issues”
  • Search for existing issues first.
  • Create an issue with a title, reproduction steps, logs, and screenshots (if necessary).

3.2 Labels & Templates

Section titled “3.2 Labels & Templates”
  • Use the labels bug, enhancement, question.
  • Follow the issue and PR templates in the repo.

3.3 Code Reviews

Section titled “3.3 Code Reviews”
  • Respond promptly to review comments in the PR.
  • Add tests or change style if reviewers suggest it.
  • After approval, your PR will be merged.

4. Community & Support

Section titled “4. Community & Support”

Good luck with contributing to OTOBO!

Frequently asked questions

How do I get started contributing code to the OTOBO project on GitHub?

To begin contributing code to OTOBO, first create a fork of the official repository located at https://github.com/RotherOSS/otobo to your personal GitHub account. Once you have successfully forked the repository, clone your fork to your local machine using the command git clone https://github.com/<your-user>/otobo.git and navigate into the newly created directory. It is best practice to create a new, descriptive feature branch for each change you intend to make, for example, git checkout -b feature/add-new-dashboard-widget. After implementing your code changes, stage them using git add . and commit them with a clear, concise, and meaningful message, such as git commit -m "Implements new dashboard widget for system overview". Finally, push your local branch to your GitHub fork using git push origin feature/add-new-dashboard-widget, which makes your changes available for a pull request.

Quellen / Sources:

What are the best practices for creating a pull request for OTOBO?

After pushing your feature branch to your fork on GitHub, you can initiate a pull request by clicking on the "Compare & pull request" button. It is crucial to provide a brief yet comprehensive description in the pull request text, explaining what your feature or bugfix accomplishes and why these changes are important for the project. This helps reviewers quickly understand the context and impact of your contribution. Ensure you select the correct target branch for your pull request; typically, this will be master for stable contributions or development for ongoing feature work. During the code review process, be prepared to respond promptly to any comments or suggestions from reviewers. You might need to add additional tests or adjust your code style as requested. Once your pull request receives approval, it will be merged into the main OTOBO repository.

Quellen / Sources:

What coding standards and testing procedures should I follow when contributing to OTOBO?

When contributing to OTOBO, adherence to coding standards is enforced using the CodePolicy tool, which is maintained by RotherOSS on GitHub. You should install this tool via cpanm CodePolicy and then execute CodePolicy --check . in the root directory of your OTOBO repository to verify compliance before submitting your code. For Perl modules, specifically those under Kernel::System::* and Kernel::Modules::*, it is mandatory to include comprehensive POD (Plain Old Documentation) documentation. Additionally, all object dependencies must be explicitly declared within our @ObjectDependencies, and it is essential to use use strict; use warnings; at the beginning of your Perl modules to ensure robust and error-free code. OTOBO also utilizes Mojolicious tests and Test::More for unit testing. Place your test files in the t/ directory and run them using prove -l t/MyModule.t to ensure your changes do not introduce regressions and function as expected.

Quellen / Sources:

How should I report bugs or suggest enhancements for OTOBO?

Before creating a new issue to report a bug or suggest an enhancement, it is crucial to search for existing issues on the OTOBO GitHub repository. This practice helps prevent duplicate reports and ensures that maintainers can focus on unique problems. When you do create an issue, provide a clear and descriptive title that accurately summarizes the problem or suggestion. For bug reports, include detailed reproduction steps, any relevant log files, and screenshots if they help illustrate the issue. For enhancements, describe the proposed feature and its benefits. It is also important to utilize the appropriate labels, such as bug, enhancement, or question, to categorize your issue. Following the issue and pull request templates provided in the repository will ensure all necessary information is captured, streamlining the review and resolution process.

Quellen / Sources:

Where can I find community support and further documentation for OTOBO development?

For community discussions and peer support related to OTOBO development, you can actively participate in the OTOBO GitHub Discussions forum, accessible at https://github.com/RotherOSS/otobo/discussions. This platform is an excellent resource for asking questions, sharing insights, and collaborating with other contributors. Additionally, the official OTOBO website, https://otobo.com/, provides links to other community resources, including mailing lists and chat channels, typically found within its "Community" section. For comprehensive developer documentation, including detailed guides on how to contribute, refer to the central OTOBO Documentation portal at https://doc.otobo.org/. Specifically, look for the "How to Contribute" section or the Developer Manual, which offers in-depth information to support your development efforts.

Quellen / Sources: