Contributing to the OTTAA Project

We would love your help with the OTTAA Project. We have compiled this useful guide to all the ways you can collaborate. Reading it carefully before you start is important to maintain consistency in the project quality and ensure a respectful and positive environment in our community.

Contents

Ways of contributing
As a developer
As a Translator
As a manual tester
As an automation tester
Code of conduct

Ways of contributing

You may contribute to OTTAA

as a developer;
as a translator;
as a manual tester;
as an automation tester.

As a developer

Required knowledge

In order to contribute as a developer, you will need to have a basic understanding of [this/these coding languge/s] and [this/these tool/s (could be a framework, library, platform)]. We also strongly recommend you be familiar with [these language/technology that might not be as important as the other two mentioned but is still important].

Setting up your IDE

Run flutter pub get to get the dependencies.
Run flutter pub run build_runner build to generate the model class code.
Run flutter run to run the project.
If you encounter any errors in model building, run flutter packages pub run build_runner build --delete-conflicting-outputs.

Reporting an issue

Any bug or hotfix that results from manual testing should be reported via an issue in our GitHub repository. Please use the template for bug reporting and provide as much information as possible about the bug, including the used version of OTTAA, and/or version of web navigator, and clear instructions on how to reproduce the bug.

Submitting a pull request

Please bear the following in mind when creating a PR:

Avoid file conflicts with the source code.
Make a detailed description of the features it applies to.
Make the PR in the corresponding branch.
Avoid your PR containing unrelated commits, keep it focused on its scope.

Commits

We use the Conventional Commits specification for our commit messages. Under this convention the commit message should be structured like this:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Bear in mind:

1) Type fix:: patches a bug in your codebase. 2) Type feat:: introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning). 3) Types other than fix:: and feat:: are allowed, for example build:, chore:, ci:, docs:, style:, refactor:, perf:, test:. 4) Footer BREAKING CHANGE or ! after type/scope: introduces a breaking API change (correlating with MAJOR in Semantic Versioning). 5) A BREAKING CHANGE can be part of commits of any type. 6) Footers other than BREAKING CHANGE may be provided and follow a convention similar to the git trailer format.

Examples

Commit message with description and BREAKING CHANGE footer:

feat: allow provided config object to extend other configs BREAKING CHANGE: extends key in config file is now used for extending other config files

Commit message with scope and ! to draw attention to breaking change

*feat(api)!: send an email to the customer when a product is shipped

Commit message with both ! and BREAKING CHANGE footer

chore!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6.

Branch naming

To name and describe our branches we use the type of change it will contain and a short description, following Git branching models.

Examples:

Instance	Branch	Description, Instructions, Notes
Stable	main	Accepts merges from Working and Hotfixes
Development	dev	Accepts merges from Features/Issues, Fixes and Hotfixes
Features/Issues	feat/*	Always branch off HEAD of Working
Fixes	fix/*	Always branch off HEAD of Working
Hotfix	hotfix/*	Always branch off Stable

Code conventions

Consistent code writing, commenting and documenting style is key to collaboration. Make sure that you read the complete Code conventions section carefully and that your code complies with our guidelines. We are using Effective Dart: Style as our main style guide for Dart.

On commenting and documenting code

To get familiarized with the code, check the [API reference] (placeholder: link to API reference, see [issue#]()). We use Dartdoc to build it and will ask you to use it as well when commenting your code. If you require assistance with Dartdoc please check Using Dartdoc below.

Classes, variables, constants, and relationships between classes should always be documented.
Your comments should be full English sentences.
Use Dartdoc to generate automatic standardized documentation for your code.
Use /// to comment your code as it is the special syntax Dartdoc looks for when generating the documentation files.
Do not use /* block comments */ for documentation:

[x]

void greet(String name) {
  /* Assume we have a valid name. */
  print('Hi, $name!');
}

Do instead:

[✓]

void greet(String name) {
  // Assume we have a valid name.
  print('Hi, $name!');
}

You can use a block comment (/* ... */) to temporarily comment out a section of code, but all other comments should use ///.

Using Dartdoc

If this is your first time using it or you have any doubts about installation, execution, or formatting, please read our Dartdoc API reference for Flutter to get started.

On code duplication

Do not copy-paste source code. Reuse it in a way that makes sense, rewriting the necessary parts.