Add suggest edits to top repo button

[dcamron]

Jupyter book has a built-in extra dropdown button for "suggest edits" per our discussion in today's meeting. This is also a chance for anyone in @ProjectPythia/education to see if you're able to push to my PR. I can always wipe out your change if it works. Attached is a screenshot of the important setting beneath the body text of your PR to enable collaboration from project maintainers. This is enabled by default for me, and if it's disabled then external maintainers will not have default write access to your branch on your fork. Otherwise we might have a permissions issue somewhere? Screenshot attached:

[github-actions]

🚀 📚 Preview for git commit SHA: 0bbd15e at: https://60660aa09d8db72173790900--pythia-foundations.netlify.app

[ktyle]

Hi @dcamron , I'm still not totally clear of the right collaborative workflow here ... so if I wanted to make a change to your fork, would I first create a fork of your fork and then attempt to make a pull request to that?

[dopplershift]

The easiest path is probably to install the GitHub Command Line Tools so that from your copy of the main repo you can do:

gh pr checkout 25

The full manual way is to add Drew's fork as a remote and check out his branch:

git remote add dcamron [email protected]:dcamron/pythia-foundations
git checkout --track dcamron/suggest-edits

Either way, after that make changes, commit them, and then do:

git push

[brian-rose]

I just successfully pushed to this branch, yay!

My commit added some verbiage to the footer directing readers' attention to the new buttons, and also says something about this on the "How to Contribute" page.

[github-actions]

🚀 📚 Preview for git commit SHA: 9603fca at: https://6066182dc94c7b3821994331--pythia-foundations.netlify.app

[brian-rose]

All good and ready to merge, but maybe others want to "practice" pushing to this branch first!

[ktyle]

Tried to push but encountered linting error once again ... seems that although I checkout out pr 25, my _build directory still had the Cartopy content I had added.

[ktyle]

(reads the error messages closer) Actually the linting worked; the error lies in the creation of the environment.

[github-actions]

🚀 📚 Preview for git commit SHA: b477bbc at: https://6067602db3f8a416aa71f574--pythia-foundations.netlify.app

[brian-rose]

@ktyle as you noted above, the old build was not the issue here, but FYI you can always do

jupyter-book clean .

to wipe out previous builds.

[brian-rose]

@dcamron said

Attached is a screenshot of the important setting beneath the body text of your PR to enable collaboration from project maintainers. This is enabled by default for me, and if it's disabled then external maintainers will not have default write access to your branch on your fork.

This raises a workflow issue. In general when we open new Pull Requests, it's probably best that they are from new feature branches of our fork, not from main. Giving people write access to our main branches sounds like it could cause trouble.

[dopplershift]

@brian-rose For git, one branch is no different than any other--main is a special one only because we humans say it is. So in my mind there's no reason to thinking giving people access to main on your fork is any different than any other.

Having said that, it's a really bad idea to be making PRs from the main branch on your fork in general. The problem is if on your laptop, you're making all your commits on main, it makes it much more challenging to then pull in changes from, say, Pythia's main branch when you want e.g. to get updated content.

TLDR; yes it's better to work on your own branch other than main, but not for the reasons you might think.

[brian-rose]

@dopplershift thanks for that, I think I "git" it

[clyne]

Hmm. Struggling to figure out how to use suggestions. After cloning dcamron:suggest-edits and rendering a local copy of the book, I opened the book, clicked "suggest edit", made my change, and then I'm given two options:

1. commit directly to the main branch
2. create a new branch and start a PR

Which do I want? I tried (1) but that seemed to actually commit the change to main (just like it says), and gave no indication that I could see that this was a suggested change (it looked like an actual change).

Thanks for any guidance.

[brian-rose]

Which do I want? I tried (1) but that seemed to actually commit the change to main (just like it says), and gave no indication that I could see that this was a suggested change (it looked like an actual change).

I'm not sure, but I suspect that option (1) only shows up if you already have write privileges in the source repo. What happens if someone who is not part of the dev team clicks the "suggested edit" button?

[dopplershift]

(1) only works since @clyne has write access. (2) would be the better way to "suggest a change", and would be the only option available to someone from the broader community. That method works pretty well for things like editing docs, where the needs for tab completion and code highlighting aren't as great as when editing code.

[clyne]

@dopplershift Good to know. Thanks. but with (2) my one-line change is failing:

https://github.com/ProjectPythia/pythia-foundations/pull/29/checks?check_run_id=2271950198

[dopplershift]

Probably best to complete the discussion over there, but nothing went wrong with the process--it's just that your change is failing linting. 😉

[brian-rose]

This seems like an important infrastructure topic. The linter is very stringent. My hope is that we can set up a workflow that is a little more encouraging of community contributions!

[dopplershift]

Well the linter is able to fix that automatically for you when you make a commit locally. Heck, most editors automatically add a newline when you save. The problem is that if you do it through the GitHub web interface, it doesn't add it nor can it run the linter.

I have no idea what config tweaks exist on the linter to make this easier or if there's any way to get it to annotate the PR to identify the problematic lines.

[brian-rose]

Yeah, and I wonder whether this will just cause more rather than less confusion for a newbie who is trying to contribute.

An alternative is to remove the "suggested edit" button and instead offer detailed instructions on how to branch, edit locally, and open a new pull request. We need to do this anyway!

[clyne]

I think suggestions as they currently work will cause confusion and frustration. Perhaps offering multiple ways to make suggestions would be best: GitHub discussions for the impatient, or branch/edit/PR for the adventurous

[dopplershift]

Another option would be to let contributors do like @clyne did and someone with write permission can correct any style issues by pushing to their branch.

[brian-rose]

Merging now, based on our discussion at last week's EWG! Sorry I meant to do this earlier.