documentation: Create CONTRIBUTING.md #5597
Draft
+196
−125
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #5597 +/- ##
=======================================
Coverage 86.15% 86.15%
=======================================
Files 393 393
Lines 56308 56308
Branches 6492 6492
=======================================
Hits 48513 48513
Misses 6262 6262
Partials 1533 1533 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
superlopuh
reviewed
Jan 31, 2026
superlopuh
reviewed
Feb 1, 2026
superlopuh
reviewed
Feb 1, 2026
superlopuh
reviewed
Feb 1, 2026
Contributor
Author
|
Thank you for reviewing! |
superlopuh
reviewed
Feb 1, 2026
superlopuh
reviewed
Feb 1, 2026
superlopuh
reviewed
Feb 1, 2026
Contributor
Author
|
Wait, I'm just noticing that we could dedup the README content. |
superlopuh
changed the title
superlopuh
reviewed
Feb 2, 2026
Comment on lines
+65
to
+100
| ## Code Style | ||
|
|
||
| We aim to follow these rules for all changes in this repository: | ||
|
|
||
| - Match existing code style and architectural patterns. | ||
| - Zero Technical Debt: Fix issues immediately. Never rely on future refactoring. | ||
| - Keep it simple: No code > Obvious code > Clever code. Do not abstract prematurely. | ||
| - Locality over DRY: Prioritize code locality. Keep related logic close together even if | ||
| it results in slight duplication. Prefer lambdas/inline logic over tiny single-use | ||
| functions (<5 LoC). Minimize variable scope. | ||
| - Self-Describing Code: Minimize comments. Use descriptive variable names and constant | ||
| intermediary variables to explain where possible. | ||
| - Guard-First Logic: Handle edge cases, invalid inputs and errors at the start of | ||
| functions. Return early to keep the "happy path" at the lowest indentation level. | ||
| - Flat Structure: Keep if/else blocks small. Avoid nesting beyond two levels if possible. | ||
| - Centralize Control Flow: Branching logic belongs in parents. Leaf functions should be | ||
| pure logic. | ||
| - Fail Fast: Detect unexpected conditions immediately. Raise Exceptions rather than | ||
| corrupt state. | ||
| - [Ask for forgiveness not permission](https://docs.python.org/3/glossary.html#term-eafp): | ||
| Assume valid keys or attributes exist and catch exceptions if the assumption proves | ||
| false. Use try-except blocks: | ||
|
|
||
| ```python | ||
| # Good | ||
| try: | ||
| return mapping[key] | ||
| except KeyError: | ||
| return default_value | ||
|
|
||
| # Bad | ||
| if key in mapping: | ||
| return mapping[key] | ||
| return default_value | ||
| ``` | ||
|
|
Member
There was a problem hiding this comment.
Actually now that I think about it, maybe we first move the existing text with minimal changes to a CONTRBUTING.md file, and then add things about code style?
Contributor
Author
There was a problem hiding this comment.
Good idea! I'll turn this into a draft, move stuff, and we'll take it from there.
superlopuh
reviewed
Feb 2, 2026
Comment on lines
+163
to
+177
| > [!IMPORTANT] | ||
| > | ||
| > ### Experimental Pyright Features | ||
| > | ||
| > xDSL currently relies on an experimental feature of Pyright called TypeForm. | ||
| > TypeForm is [in discussion](https://discuss.python.org/t/pep-747-typeexpr-type-hint-for-a-type-expression/55984) | ||
| > and will likely land in some future version of Python. | ||
| > | ||
| > For xDSL to type check correctly using Pyright, please add this to your `pyproject.toml`: | ||
| > | ||
| > ```toml | ||
| > [tool.pyright] | ||
| > enableExperimentalFeatures = true | ||
| > ``` | ||
|
|
Member
There was a problem hiding this comment.
I would probably duplicate this in the readme, it applies to projects that depend on xDSL also, without it Pyright doesn't typecheck the project.
Contributor
Author
There was a problem hiding this comment.
Made sure to duplicate this line in #5604
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Clear code quality guidelines (especially valuable if code generation tooling is used).
https://lkml.org/lkml/2026/1/7/1888