Skip to content

Latest commit

 

History

History
110 lines (91 loc) · 5.62 KB

CONTRIBUTING.md

File metadata and controls

110 lines (91 loc) · 5.62 KB
Raw

Contributing to [Project Name]

Thank you for considering contributing to the Konveyor Rulesets project! We welcome all contributions—whether they’re issues, code, documentation, or suggestions for new features. Below, you’ll find our guidelines for contributing.

Table of Contents

  1. Code of Conduct
  2. How Can You Contribute?
  3. Getting Started
  4. Submitting an Issue
  5. Submitting a Pull Request
  6. Coding Guidelines
  7. Commit Message Guidelines
  8. Setting Up the Environment
  9. Resources

Code of Conduct

This project follows Konveyor's Code of Conduct. By participating, you agree to abide by its terms.

How Can You Contribute?

Here are some ways you can help:

  • New rules: You can contribute to the Rulesets project with any new rules you might have come up with for doing your own migrations, as long as they are related to open-source technologies and you follow the guidelines in this document.
  • Feature Requests: You can request new rules for existing technologies not yet covered by our rulesets.
  • Bug fixes: Fix bugs in rules, or create new tests for uncovered scenarios.
  • Documentation: Improve our documentation, tutorials, or guides.

Getting Started

  1. Fork the repository and create a new branch from main.
  2. Follow these instructions to install Kantra: Setting up Kantra and developing rules.
  3. Make your changes according to the Rule creation guidelines, test them, and commit your work.

Rule creation guidelines

There are a few conventions that we follow when creating rules:

Directory structure

Rules can be found within the default/generated folder. Within this folder, rules are organized by target technology. Source and target technologies are the technologies to migrate to and from, respectively. If a new target technology is to be added, a new folder should be created to cover for it. Within each target directories, additional directories can be created to further segregate the rules according to their source technologies. For instance, Within the eap8 target folder, we could have eap6 and eap7 folders covering for migration to eap8 from eap 6 and 7 respectively.

Additionally, within each rules directory, a test directory should be created to place the rules's tests. Since each test needs data, a data directory must also be created inside test. For instance:

.
└── target
    ├── source1
    │   ├── rules-1.yaml
    │   ├── rules-2.yaml
    │   └── tests
    │       ├── data
    │       │   ├── rules-1
    │       │   └── rules-2
    │       ├── rules-1.test.yaml
    │       └── rules-2.test.yaml
    └── source2
        └── ...

Inside of each data folder, it is recommended to segregate the test data, so that each folder within it contains the data for the tests of a single rules file. This way, other tests will be less affected by changes in the data.

Tests organization and file naming

  • It is recommended that a single rules file holds rules for the migration of a related set of concerns within its particular migration path. For instance, if migration from A to B implies changes related to data sources and web services, two different rule files should be created, one containing the rules related to data sources and another one for web services. This makes it easier to find rules, create tests and data for them, and keep the structure organized in general.

  • Rules should be named using hypens for word separation. Also, names for the rule files should indicate the target technology and the concern of the rules they contain. If needed, they can also indicate the source technology.

  • Test files should be named after the rule file they cover in the following way: <rule-file>.test.yaml

Rule IDs

Rule IDs must be unique within the rulesets being used, and contain in themselves the name of the rule file plus a number. These numbers must have 5 digits and increase by 10 each time, to follow a convention set in the old Windup rules. For instance, within a rules-eap-web.yaml file:

- ruleID: rules-eap-web-00001
  ...
- ruleID: rules-eap-web-00010
  ...

Submitting an Issue

  • Search existing issues to avoid duplicates.
  • Provide as much detail as possible, including steps to reproduce.
  • Label the issue appropriately (bug, enhancement, question, etc.).

5. Submitting a Pull Request

  • Ensure your branch is up-to-date with main.
  • Make sure all tests pass before submitting.
  • Include a detailed description of your changes.
  • Reference related issues in the description (e.g., Fixes #123).
  • Follow our Commit Message Guidelines.

6. Coding Guidelines

  • Formatting: Follow Project Style Guide for consistent coding practices.
  • Naming Conventions: Use clear, descriptive names.
  • Documentation: Document new methods, classes, and changes to existing functions.
  • Testing: Write unit tests for new features and bug fixes.

7. Commit Message Guidelines

  1. Use the present tense ("Add feature" not "Added feature").
  2. Keep messages concise but informative (max 72 characters).