Contributing

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
• Open an issue first
• Issue & PR templates
• Code of Conduct
• What CI actually builds
• The PR checklist
• Dependabot
• Coding standards
• Reporting security issues
• Contact
• See also

---

Fork & pull-request workflow

The flow from .github/CONTRIBUTING.md:

1. Fork https://github.com/Taiizor/Sucrose on GitHub.

2. Clone your fork:

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

3. Make your changes, following the Code Conventions.

4. Commit with a descriptive title plus an explanation:

   git commit -m "Title: explanation."

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

   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.

6. Open a Pull Request to the main repository, targeting develop.

7. 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.
nuxt-deploy.yml	every push to develop	Builds and deploys the project website in .pages/ (Nuxt + Tailwind, bun) to GitHub Pages. Independent of the .NET app.

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

• Building From Source
• Code Conventions
• Extending Sucrose
• Repository Layout
• Security Policy
• Translating with the Localizer
• Getting Help
• Logs & Diagnostics