Software Engineering for Eclipse Qrisp

[bastibock]

Hi everyone,

I want to start this discussion to help create contributing guidelines for Eclipse Qrisp and collaboratively work on this.

The uploaded file is initially from @PietropaoloFrisoni and @ACE07-Sev .

Looking forward to the discussion!
CONTRIBUTING.md

[PietropaoloFrisoni]

Thanks @bastibock !

I mentioned this in the meeting, but I’m repeating it here for visibility.

I originally wrote this guideline with potential new contributors in mind, especially in the context of supporting the refactoring effort. @tcholtchev mentioned that he may soon have students who could help, which is exactly the kind of scenario I had in mind.

If we want to evolve this into a more general “contributing guidelines” section (which we’ll likely need at some point, so we might do that now), I think some parts should be revised. For example, the first paragraph (“Improving the Core Components of the Codebase”) would probably need to be reworked, as it may not fit well in that context.

If helpful, I’m happy to take what I’ve written and turn it into a proper guideline section for the documentation (I could open a PR in qrisp later this week or early next week). This will be for external contributors as well, so we don't need to mention management software like Jira (and we still need to decide what to use). It would be easy for everyone to provide comments, suggestions, or push commits in the PR directly so that we all collaborate on this. Let me know what you think 🙂

P.S. @purva-thakre mentioned she’d be interested in handling the ruff check implementation (including selecting the rules), which would be a great and very useful addition.

[purva-thakre]

. @purva-thakre mentioned she’d be interested in handling the ruff check implementation (including selecting the rules)

Thanks Pietro! I volunteered because I already have an older configuration for this handy since I implemented these changes in another project. I will have to tailor the configuration to be specific to Qrisp's needs.

I will begin with the rules mentioned in the code block below and then add newer rules based on suggestions from everyone else. If you go to the rules page, you can take a look at the full set of rules available via ruff.

The code block below will be added to the pyproject.toml file. Then it is straightforward as running ruff check --fix (linter) or ruff format (formatter) in the main Qrisp directory. Of course, when we are done making changes across all the files, we can add ruff checks in the CI and the ruff pre-commit hook too.

I will also go ahead and link to relevant sections in ruff's docs:

• https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
• https://docs.astral.sh/ruff/rules/#pydocstyle-d
• https://docs.astral.sh/ruff/rules/#isort-i
• https://docs.astral.sh/ruff/rules/#pylint-pl
• https://docs.astral.sh/ruff/rules/#pyflakes-f

[tool.ruff]
exclude = ["__init__.py", "docs/"]
line-length = 120
target-version = "py312" # will be changed to consider other python versions as well
force-exclude = true


[tool.ruff.lint]
select = ["I", "E", "W", "D", "PL", "F"]
# ruff configuration
# E, W -- pycodestyle
# D -- pydocstyle
# I -- isort
# PL -- pylint
# F -- pyflakes


# Rules considered over other incompatible ones
exclude = []


ignore = ["D407", "D203", "D213", "D416", "PLR0912", "PLR0911", "PLR0915", "PLR2004", "PLR0913", "F811", "E203"]
# Rules Ignored

# D407 - Ignored because ==== under a section heading is considered as a missing underline.
# pydocstyle considers ----- an underline.

# D212 and D211 specially selected due to following incompatibilities
# warning: `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible. Ignoring `one-blank-line-before-class`.
# warning: `multi-line-summary-first-line` (D212) and `multi-line-summary-second-line` (D213) are incompatible. Ignoring `multi-line-summary-second-line`.

# D416 was adding a semicolon after some section headings when ruff's automated --fix was was used
# As this was not added evenly after all section headings, we ignore this. 

# PLR0912 -- Checks for functions or methods with too many branches. The default number is 12. 
# PLR0911 -- Checks for functions or methods with too many return statements. The default number is 6.
# PLR0915 -- Checks for functions or methods with too many statements. The default number is 50. 
# PLR2004 -- Checks if an equality or an inequality is compared to a variable or a num (prefers variable pre)
# PLR0913 Too many arguments in function definition
# F811 -- Checks for variable definitions that redefine (or "shadow") unused variables 
# E203 -- Whitespace before ':'. This rule conflicts with Black's formatting style.
# It was removing definitions with the same name creating conflicts in test_is_stochastic.py

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["I001", "F401"]
# I001 - skip checking Import block is un-sorted or un-formatted
# F401 - Checks for unused imports, applying fixes to __init__.py currently under review
# skip checking all the .py files in the examples gallery
"docs/content/examples/*" = ["I", "E", "W", "D", "PL", "F"]

[purva-thakre]

I have recently come across a tool for AI reviews: https://www.coderabbit.ai/

Quite a few projects in the quantum ecosystem already utilize it. Adding a comment for us to figure out if it is worth using this in the future.