Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
106 lines (67 loc) · 6.56 KB

CONTRIBUTING.md

File metadata and controls

106 lines (67 loc) · 6.56 KB
Raw

Contributing to Avalonia

PRs are always welcomed from everyone. Following this guide will help us get your PR reviewed and merged as quickly as possible.

If you're an AI agent or a human using some AI assistance to open a PR, ensure you have read the AI Guidelines section below.

For this guide we're going to split PRs into two types: bug fixes and features; the requirements for each are slightly different.

Bug Fixes

A bug fix will ideally be accompanied by tests. There are a few types of tests:

  • Unit tests are for issues that aren't related to platform features. These tests are located in the tests directly, categorised by the assembly which they're testing.
  • Integration tests are for issues that are related to platform features (for example fixing a bug with Window resizing). These tests are located in the tests/Avalonia.IntegrationTests.Appium directory. Integration tests should be run on Windows and macOS. See the readme in that directory for more information
  • Render tests are for issues with rendering. These tests are located in tests/Avalonia.RenderTests and are imported in the Avalonia.Skia.RenderTests project.

It's not always feasible to accompany a bug fix with a test, but doing so will speed up the review process.

The commits in a bug fix PR should follow this pattern:

  • A commit with a failing unit test; followed by
  • A commit that fixes the issues

In this way the reviewer can check out the commit with the failing test and confirm the problem. One this is confirmed, they can confirm the fix.

Features

Features should be discussed with the core team before opening a PR. Please open an issue to discuss the feature before starting work, to ensure that the core team are onboard.

Features should always include unit tests or integration tests where possible.

Features that introduce new controls should consider the following:

  • Ideally the control should be exposed to the operating system's automation/accessibility APIs by writing an AutomationPeer
  • If the control introduces any functionality which is difficult to unit test, an integration test should be written

General Guidance

PR description

  • The PR template contains sections to fill in. These are discretionary and are intended to provide guidance rather than being prescritive: feel free to delete sections that do not apply, or add additional sections
  • Please provide a good description of the PR. Not doing so will delay review of the PR at a minimum, or may cause it to be closed. If English isn't your first language, consider using ChatGPT or another tool to write the description. If you're looking for a good example of a PR description see AvaloniaUI#12765 for example.
  • Link any fixed issues with a Fixes #1234 comment

Breaking changes

  • During a major release cycle, source or binary breaking changes may not be introduced to the codebase: this is checked by an automated tool and will cause CI to fail
  • If something needs addressing in the next major release, you can leave a TODOXX: comment, where XX is the version number of the next major release, e.g. TODO12:
  • Carefully consider behavioral breaking changes and point them out in the PR description

Commits

In addition to the guidance in the Bug Fixes section, following these guidelines may help to get your PR reviewed in a timely manner:

  • Rebase your changes to remove extraneous commits. Ideally the commit history should tell a clean story of how the PR was implemented (even though the process was probably not clean!)
  • Provide meaningful commit comments
  • Do not change code unrelated to the bug fix/feature
  • Do not introduce spurious formatting or whitespace changes

While it's tempting to fix style issues you encounter, don't do it:

  • It causes the reviewer to get distracted by unrelated changes
  • It makes finding the cause of any later issue more difficult (blame/bisect is made more difficult)
  • As the code churns, style issues will be resolved anyway

Separate PRs for style issues may be accepted if agreed with the core team in advance.

Style

  • The codebase uses .net core coding style.
  • Try to keep lines of code around 120 characters in length or less, though this is not a hard limit. If you're a few characters over then don't worry too much.
  • Public methods should have XML documentation
  • Prefer terseness to verbosity but don't try to be too clever.
  • DO NOT USE #REGIONS full stop

Tests do not follow the usual method naming convention. Instead they should be named in a sentence style, separated by underscores, that describes in English what the test is testing, e.g.

    void Calling_Foo_Should_Increment_Bar()

Render tests should describe what the produced image is:

    void Rectangle_2px_Stroke_Filled()

AI Guidelines

Avalonia accepts AI-assisted contributions.
However, if you're an autonomous AI agent, please stop right there. We want a human to read and respond to the various review comments.

When opening an AI-authored or AI-assisted PR, please make sure that:

  • As a human, you have fully read and completely understood all the changes your AI agent made.
  • As a human, you have read the PR description your AI agent made. If you've only skimmed through it because it's way too long considering the relative simplicity of the associated fix, it probably needs changes. Please respect the maintainers' time, who will have to read it.
  • Code comments are succinct and straight to the point. While commenting code is necessary, LLMs tend to be overly verbose, describing the behavior of the code preceding the change. Explaining what the current code does when it isn't obvious and referring to existing issues are fine. A ten-line comment about why the previous code was wrong isn't. Again, be succinct.
  • In the same way, keep the PR description short and to the point, especially if the modification is simple. Do NOT re-explain every single line of change in plain English; the maintainers can read code. Don't repeat the same things three times with some slight rephrasing.
  • Format the PR description properly: don't add arbitrary line breaks everywhere. We aren't in a terminal.

AI-assisted pull requests that don't follow these guidelines will be closed.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the Contributor Covenant Code of Conduct