Repository navigation
Conversation
✅ Deploy Preview for spyder-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
CAM-Gerlach
left a comment
CAM-Gerlach
left a comment
There was a problem hiding this comment.
First off, the issue requested doing this across all files in the repo, not just in and around the one arbitrary example.
Furthermore, as I stated there, the best approach is replacing the prose linked targets with named ones, which preserves the structure, avoids duplication/retains DRYness and keeps the URL separate from the prose, simplifying matters for translators.
However, unfortunately there's a much bigger issue with this PR, especially given it was explicitly intended to be for a good first issue for contributor new to open source such as yourself: Not only the code but the PR description appears to be 100% AI generated (and likely agent-posted), without any disclosure.
This directly contravenes the AI usage policy that our project along with the others involved in the sustainability series program have adopted, which you were explicitly reminded of in your orientation emails, in both office hours, and in our Discord. Specifically, using LLMs to assist in coding is allowed but must be disclosed, which it was not; that contributors must understand the changes and describe them in their own words in the PR description, which they did not; and that under no circumstances should LLMs be used to generate text for nor replace genuine human to human communication when replying to a reviewer, which it was).
Furthermore, policy aside having an LLM do the entire contribution process for you kinda defeats the purpose of a "good first issue" to begin with in terms of learning how to contribute and communicate in an open source project. To be sure, LLMs can be useful tools in this regard toward gaining understanding of a new codebase, suggesting approaches to solve an issue and reviewing your work. However, the issue arises when you just point the LLM at an issue and tell it to make a PR, even having it read and respond to the human reviewers for you. The whole point is for you to learn and gain experience with the process, which using a LLM agent to do the whole thing for you robs yourself of.
Finally, just to note as of last week on our Discord we've pinged and reminded everyone in this program to please only claim one issue at a time until your PR is merged, so there are enough to go around for everybody--I see you also opened spyder-ide/docrepr#59 at the same time.
|
For the reasons explained above, I unfortunately will have to close this PR, as to actually accomplish the purpose of a "good first issue" you'll need to actually go through and experience the contributing process yourself. Let us know (here or on Discord) if you have any questions, and we'll be happy to assist. Just to note--to avoid any possible confusion going forward, I've merged PR #442 which adds an explicit statement of the AI policy in this repo's Contributing Guide as well as an |
Description of Changes
Convert the six mid-sentence links in the "Join our community" section of
doc/index.rstfrom reference-style targets to inline links, and remove the now-unused.. _target:definitions. As noted in the issue, reference-style links in the middle of a sentence can't be translated properly; inline links keep each sentence as a single translatable unit.Built locally with
python -m sphinx -n -W --keep-going doc doc/_build/html(no warnings/broken links) and checked withsphinx-lint.Note: the same reference-style pattern exists elsewhere in the docs; happy to do a repo-wide follow-up if wanted (it would also touch STYLEGUIDE line 83).
Issue(s) Resolved
Fixes #386