Skip to content

AI Usage

This page documents how AI assistants and code-generation tools are expected to be used when contributing to Flowing Code's open source add-ons and libraries.

Draft

This is an initial draft. The final policy will be refined by Flowing Code and replace this content.

Principles

AI tools (coding assistants, code-generation models, review assistants, etc.) can accelerate development and improve consistency, but the responsibility for every contribution remains with the human contributor.

  1. You are accountable for what you submit. Whether code, tests, or documentation is hand-written or AI-assisted, the contributor is responsible for its correctness, security, performance, and alignment with the project's conventions.
  2. Verify, don't trust. AI output should be read, understood, tested, and challenged like any other code. Run the test suite and exercise the change locally before submitting.
  3. Keep the human in the loop on design. Use AI for implementation, refactoring, scaffolding, and documentation drafts — but architectural decisions, public-API design, and trade-off analyses should be deliberate human choices.
  4. Match the project's voice and conventions. AI tends to produce generic patterns. Bring contributions in line with the code style and commit message conventions before submitting.

What is encouraged

  • Implementation assistance — writing boilerplate, applying patterns you already know, generating test cases for behavior you've defined.
  • Refactoring suggestions — improving readability, extracting helpers, applying consistent naming.
  • Documentation drafts — JavaDoc, README content, migration guides, and demo descriptions. Always review for accuracy before publishing.
  • Test generation — drafting unit and integration tests, especially for edge cases. Verify that the tests actually exercise the intended behavior.
  • Code review assistance — using AI to surface potential issues in a diff. Treat the output as a hint, not a verdict.

What is discouraged

  • Submitting unreviewed AI output. A PR that the author hasn't read line by line is not acceptable.
  • AI-generated commit messages that don't reflect the change. Commit messages must follow the Conventional Commits guidelines and accurately describe what the commit does.
  • Large, unfocused PRs. AI makes it easy to produce sweeping changes; keep contributions logically atomic and reviewable.
  • Plausible-sounding but wrong API references. Verify imports, class names, method signatures, and Vaadin API usage against the actual codebase and current Vaadin documentation — not against the model's training data.

Confidentiality

Open source repositories contain no confidential material, so contributors are free to use AI assistants when working on them. When contributing changes that touch both an open source project and a private Flowing Code project, do not paste private code, customer data, or internal credentials into third-party AI tools.

Attribution

There is no requirement to disclose AI assistance in commits or PR descriptions. If you used Co-authored-by: to attribute a contribution to an AI tool, follow the same syntax as any other co-author:

Co-authored-by: assistant-name <noreply@example.com>

The accountability for the contribution remains with the human author named in the commit's Author: field.

When in doubt

If a contribution makes you uncomfortable — because the AI output feels too generic, the change is larger than you'd normally make by hand, or you don't fully understand a section — slow down, review carefully, and ask for input on the PR before requesting a merge.