Menu ▾ ▴

Contributing

Bayram Emekli

Contributing

Audience: developers / contributors. Sucrose is an open-source (GPL-3.0) Windows wallpaper engine, and contributions are welcome. This page describes the full contribution workflow — fork, branch, commit, pull request — plus the issue/PR templates, the Code of Conduct, what CI actually checks, the Dependabot setup, and how to reach the maintainer. The default (and target) branch for all pull requests is develop, not main.

Contents

Fork & pull-request workflow

The flow from .github/CONTRIBUTING.md:

  1. Fork https://github.com/Taiizor/Sucrose on GitHub.
  2. Clone your fork:

bash git clone https://github.com/Taiizor/Sucrose.git

  1. Make your changes, following the Code Conventions.
  2. Commit with a descriptive title plus an explanation:

bash git commit -m "Title: explanation."

  1. Push to your fork. The repository's default branch is develop:

bash git push origin develop

The shipped .github/CONTRIBUTING.md historically said git push origin main; the project's default branch is actually develop, so push and open your PR against develop.

  1. Open a Pull Request to the main repository, targeting develop.
  2. Review — maintainers review, may ask follow-up questions, then merge.

Open an issue first

For new features or significant changes, open an issue first to discuss before writing code. This avoids wasted effort on changes that may not fit the project's direction. Small fixes (typos, obvious bugs) can go straight to a PR.

Issue & PR templates

Issue templates live in .github/ISSUE_TEMPLATE/. Blank issues are disabled (config.yml → blank_issues_enabled: false) — you must pick a template. The template chooser's contact link points to the GitHub Discussions tab for general questions.

Template Label Key sections
bug_report.md bug Bug Description, To Reproduce, Expected Behavior, Screenshots/Video, Desktop (OS + which wallpaper was running), Additional Context, and a required Log File section.
feature_request.md enhancement Problem statement, desired solution, alternatives considered, additional context.

Bug reports require a log file. Produce one in any of these ways (also see Logs & Diagnostics):

  • Tray icon → Report Issue → Create Log File; or
  • Sucrose settings (gear, top-right) → System → Log Files → Create; or
  • Navigate to C:\Users\<UserName>\AppData\Roaming\Sucrose\Log and attach the relevant log.

Reminders before filing: one issue per bug, search for duplicates first, use a descriptive title, and check the wiki troubleshooting pages (see Troubleshooting (Common)).

Code of Conduct

The project adopts the Contributor Covenant v2.1 (.github/CODE_OF_CONDUCT.md). It includes the standard pledge, standards of acceptable behavior, and a four-step enforcement ladder:

  1. Correction
  2. Warning
  3. Temporary Ban
  4. Permanent Ban

Code of Conduct enforcement concerns can be raised with the maintainer at taiizor@vegalya.com.

What CI actually builds

A common misconception: there is no automated full-app build or release CI. The workflows in .github/workflows/ are:

Workflow Trigger What it does
codeql-analysis.yml push/PR to develop, and nightly (cron: '0 0 * * *') on windows-2022 CodeQL analysis, language matrix csharp only. Builds only 7 src/Library/ projects: Pipe, Memory, Signal, Manager, Resources, Transmission, XamlAnimatedGif (Mpv.NET is excluded). Uses .NET 11.0.x quality preview; restore + build with -p:UseSharedCompilation=false.
congratulations.yml first-time contributor's first issue or first PR to develop Posts a welcome comment (via actions/first-interaction@v3) with the PR checklist below.

Consequences for contributors:

  • CI does not compile the executables, engines, the Portal, the shared projects, or the full solution. A PR that breaks any of those still passes CI. Build locally before opening a PR — see Building From Source.
  • There is no automated test suite (no test projects exist). Validate behavior by running the app.
  • EnforceCodeStyleInBuild=true makes .editorconfig violations build errors locally, but CI only enforces this on the 7 Library projects.

The PR checklist

The congratulations.yml welcome comment posts a checklist on a contributor's first PR. Use it as your pre-submit gate:

  • Follow the project's code style.
  • Tested the change locally.
  • Updated documentation where relevant.
  • CI is passing.
  • Clear, descriptive commit messages.

Dependabot

.github/dependabot.yml configures two ecosystems, both run monthly (Monday 09:00, Europe/Istanbul):

Ecosystem Directory Open-PR limit Labels Commit prefix
nuget / 10 dependencies, nuget deps (with scope)
github-actions / 5 dependencies, github-actions ci (with scope)

NuGet versions are centrally managed in Directory.Packages.props with transitive pinning, so Dependabot PRs update versions there.

Coding standards

The contribution guidelines ask you to:

  • Comply with the project LICENSE (GPL-3.0).
  • Keep code readable and maintainable and follow good coding standards.
  • Attribute sources and avoid copyright violations.

In practice, that means following the strict repository conventions: the namespace-alias acronym rule, the directory-role layout, and the enforced .editorconfig style (4-space indentation, CRLF line endings, block-scoped namespaces, I-prefixed interfaces, explicit types over var, expression-bodied accessors only). All of this is documented in Code Conventions. For structural changes (new settings, engines, shared projects) follow the recipes in Extending Sucrose.

Reporting security issues

Do not open a public issue for a vulnerability. Report it privately by email so it can be fixed before disclosure — see Security Policy for the full responsible-disclosure process.

Contact

  • GitHub Issues — bugs and feature requests (use a template; blank issues disabled).
  • GitHub Discussions — general questions.
  • Email — taiizor@vegalya.com.

Other governance documents in .github/: SECURITY.md, PRIVACY_POLICY.md, TERMS_OF_SERVICE.md, FUNDING.yml, and READMEs in four languages (README.md, README.tr-TR.md, README.ja-JP.md, README.zh-CN.md).

See also

Related

Wiki: Building From Source
Wiki: Code Conventions
Wiki: Extending Sucrose
Wiki: Getting Help
Wiki: Home
Wiki: Localization Coverage
Wiki: Security Policy
Wiki: Translating Localizer
Wiki: _Sidebar

Auth0 Logo