Add: ruff setup and instructions on autoformatting with vscode #34
Conversation
| @@ -0,0 +1,98 @@ | |||
| # Linting and Code Formatting | |||
There was a problem hiding this comment.
maybe add some discussion on hatch fmt (which only runs ruff). We want to run codespell and markdownlint and others potentially. What is the best way to do this?
https://hatch.pypa.io/latest/config/internal/static-analysis/
There was a problem hiding this comment.
I looked into using hatch fmt with Jupyter projects but decided against it, since without using https://hatch.pypa.io/latest/config/internal/static-analysis/#persistent-config the rules are opaque and not visible to editors, and I didn't want to commit such a large file to the repos.
There was a problem hiding this comment.
ok this makes sense. so we should for now, not use that.
how does jupyter handle linting or where do you all land?
| want to set up pre-commit locally, or someone who wants to submit a pull request | ||
| (e.g., as a first contribution!) fully from the GitHub interface, you can enable | ||
| the bot to run pre-commit checks and fixes in the pull request yourself, as a | ||
| maintainer, before you merge the PR. |
There was a problem hiding this comment.
One thing to bear in mind with this is that when the bot pushes a fix, contributors need to pull down that fix before making further changes, which can be confusing.
There was a problem hiding this comment.
oh right - good point! Would being a bit stronger about the language - only run pre-commit right before you merge the PR help clarify?
There was a problem hiding this comment.
I meant if the bot itself pushes a fix it can be confusing, which I don't think can be configured to run on demand.
There was a problem hiding this comment.
AHHH ok. i do use the bot on demand - even in our repos here at pyos.
you can set the bot up to NOT autoformat and just check the repo. then when ready, use pre-commit autofix to call the bot.
my preferred workflow is
setup precommit.
Allow users to use it (or not)
i use it locally as a maintainer,
when a contributor submits a pr, i review and ignore linting until the end. when we are ready to merge, run precommit autofix on the pr. and the bot does it's thing.
the bot can't fix spelling errors.
what i'm trying to figure out here that i wonder if you / jupyter has solved is how should we suggest people run linters if pre-commit is confusing. (i understand it is confusing!)
There was a problem hiding this comment.
Please remember also the security issues that @ofek mentioned on Slack. I think, that's important to note here.
| issues in your files, it will not actually commit your files to history. This | ||
| can be confusing for even seasoned developers if they haven't used pre-commit | ||
| before. | ||
| * Some prefer to set up autoformatters that run every time you save a file in |
There was a problem hiding this comment.
We've mitigated this in some projects by relying on standard config as much as possible so that the scripts/IDEs can be run independently of pre-commit, and leaning on hatch environments for complex tasks.
There was a problem hiding this comment.
so helpful - i think the same question as above - could you perhaps direct me to an example of how you run linters / formatter? i could see a hatch lint that we create or... ?
There was a problem hiding this comment.
There was a problem hiding this comment.
Thank you for this @blink1073 !!
|
|
||
| ## Spyder | ||
|
|
||
| todo: add instructions here |
There was a problem hiding this comment.
I believe this is not yet implemented: spyder-ide/spyder#21357
| }, | ||
| }, | ||
| // TODO: figure out how the formatter is selected for notebooks | ||
| "notebook.formatOnSave.enabled": true, |
There was a problem hiding this comment.
The Ruff VSCode Details page shows:
{
"notebook.formatOnSave.enabled": true,
"notebook.codeActionsOnSave": {
"notebook.source.fixAll": "explicit",
"notebook.source.organizeImports": "explicit"
},
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff"
}
}
| autofix_prs: false | ||
| # Frequency of hook updates | ||
| autoupdate_schedule: weekly | ||
| autoupdate_schedule: quarterly |
There was a problem hiding this comment.
I'm in doubt about enabling auto update on a schedule. Wouldn't you want every contributor to run the same hook versions as in the main project branch? In my view, it's up to the maintainer to bump hook versions.
There was a problem hiding this comment.
Do you still know someone who downloads PDFs of documentation these days? I'd be curious about usage numbers over all of readthedocs. I don't enable PDF on my projects any longer.
There was a problem hiding this comment.
Ok i'm responding to these comments in this closed PR (which i know is confusing!!).
This is a great question!!
My understanding is that PDFs are ideal for some people—especially those with less-than-good internet—because they can download once and read later offline. So that is why I generally include them. It is possible that for most people, this isn't an issue. But I've worked in areas where the internet is really challenging and students are on phones and tablets, and being able to download things is useful. we could chat more about this in a separate issue too!
| * For beginner contributors, running pre-commit hooks can be confusing. You need | ||
| to understand that each time you commit, it will run the checks. If it finds | ||
| issues in your files, it will not actually commit your files to history. This | ||
| can be confusing for even seasoned developers if they haven't used pre-commit | ||
| before. |
There was a problem hiding this comment.
| * For beginner contributors, running pre-commit hooks can be confusing. You need | |
| to understand that each time you commit, it will run the checks. If it finds | |
| issues in your files, it will not actually commit your files to history. This | |
| can be confusing for even seasoned developers if they haven't used pre-commit | |
| before. | |
| * For beginner contributors, running pre-commit hooks can be confusing. You need | |
| to understand that each time you commit, it will run the checks. If it finds | |
| issues in your files, it will not actually commit your files to history. This | |
| can be confusing for even seasoned developers if they haven't used pre-commit | |
| before. If pre-commit hooks are not to your liking, please be aware that it is _your_ | |
| local development environment. You are not obliged to install them in the first place | |
| or you can remove them with `pre-commit uninstall`. If you want to avoid the hooks | |
| for a single commit, you can also skip them by running `git commit --no-verify`. Of course, | |
| avoiding these hooks may mean that you later need to format your code by other means. |
| can be confusing for even seasoned developers if they haven't used pre-commit | ||
| before. | ||
| * Some prefer to set up autoformatters that run every time you save a file in | ||
| your preferred code editor (like VSCode). More on that below. |
There was a problem hiding this comment.
| your preferred code editor (like VSCode). More on that below. | |
| your preferred code editor (like VS Code). More on that below. |
| want to set up pre-commit locally, or someone who wants to submit a pull request | ||
| (e.g., as a first contribution!) fully from the GitHub interface, you can enable | ||
| the bot to run pre-commit checks and fixes in the pull request yourself, as a | ||
| maintainer, before you merge the PR. |
There was a problem hiding this comment.
Please remember also the security issues that @ofek mentioned on Slack. I think, that's important to note here.
| You can add this configuration to your workspace to ensure ruff is run on your | ||
| files every time you edit and save them. |
There was a problem hiding this comment.
Important to mention that there is also a UI for this. Open your settings, e.g., ctrl + , and search for ruff. You can also find it under Extensions. Choose to store settings either for your User or for the Workspace. Choose options like "Ruff > Lint: Run onSave" via the interface.
|
Whoops, was that intentional? |
|
oh no it wasn't. what did i do? |
|
OH i know what i did! i deleted my fork because i wanted to create a demo lesson about forking a repo. let me see if there is some way that i can recreate this ... eeks!! |
I think i need a bit of input on this pr - essentially it introduces pre-commit but also autosave (which has different formatters than ruff by itself.
I think we might want to setup a custom hatch environment to run tools (as an alternative to pre-commit). but i'm not 100% certain what is best here.