Correct way to Collaborate via Codespaces

[Adam Gilbert]

Hi everyone,

I apologize if this is described somewhere. I checked Sections 2.1 and 2.2 of the PreTeXt Author Guide and also looked through previous conversations here. I'm wondering what the "correct" way to coauthor in PreTeXt via GitHub Codespaces is. So far, I've followed the instructions at the PreTeXt Codespaces repo to template the repository. I've created a Codespace on the main branch in my repository. Everything seems to work well for me -- I can create and edit files, build the book, commit and push changes to the main branch, and I can deploy the project to its gh-pages branch.

I've added my collaborator with direct access to the repo, so she should be able to push directly to the project. I had her log in to GitHub and navigate to the repository. She couldn't see the Codespace that I created, which makes sense to me. I had her click on the Code button and add her own Codespace on the main branch. Right away, this seems to work well -- she can create/edit files, build the book, and commit/push changes to the original repository just like I can. Once she closes the Codespace and returns to the project though, her Codespace isn't available from the original repository. It has moved to a fork of the repository on her account instead. If she opens her Codespace and makes changes there, she no longer has permissions to push to the original repository. I suppose that, in this configuration, she should be able to commit/push changes to her fork and then create pull requests. Is this the expected/appropriate organization?

Please forgive (and feel free to advise on) any bad GitHub practices or understanding here. My collaborator is a true novice and I know just enough to be semi-functional.

Thanks for any advice people can provide!

--Adam

[Sean Fitzpatrick]

I'm not using code spaces, but I think it should be no different than if you're each building on a computer.

So you each need a code space, which I would guess is easiest to accomplish with a fork.

Your collaborators can build on their own code space to test, and then send a pull request upstream when things are ready to go.

--
You received this message because you are subscribed to the Google Groups "PreTeXt support" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-suppo...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-support/3faa2185-63ec-430c-b154-ecdb838cad51n%40googlegroups.com.

[Oscar Levin]

First some general advice: I think there are three reasonable workflows for collaboration.  Having contributors work on a fork and submit pull requests, and then remember to sync their fork regularly is one of them.  The other two are to have contributers with push access to the repository push directly to it, but either to insist that all changes be merged into the main branch via a pull request, or to allow everyone to push directly to main.  This last approach is the least clicks, but has the most potential for messes.

It sounds like you were trying for one of the second two approaches.  Perhaps you did not give your collaborator the correct permissions, or didn't do so early enough that the code space didn't register them, suggesting instead to work on a fork.  So you could try again.  Working on a fork should be fine though, just remember to have your collaborator regularly sync, (which can be done from the fork GitHub repository page).  Oh, and they won't be able to deploy, although you could set up a GitHub action to do that automatically when the pull request is accepted.

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-support/CAH%2BNcPasUet%3DKMXKLEnp0B5oBg%3DNdOPsvYKmDD%3D5n2E1-tbFtQ%40mail.gmail.com.

[Adam Gilbert]

Thank you Sean and Oscar. These responses are helpful.

Oscar, you are right -- I was attempting to set up the second approach with both of us able to push directly to main. I'll double-check the permissions I have for her and then try to set up the Codespace again. As you said, working on a fork will be fine as well. In fact, it sounds like this would be a safer option than letting both of us freely push to main without forcing pull requests.

Thank you both again. I appreciate your insight!

--Adam

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-support/CAOU9BaXgzd-nxi75-0-fitTcDPW_1rqwf1Y-r8XrqdEH2ecM9w%40mail.gmail.com.

--

Adam Gilbert, PhD

Associate Professor of Mathematics

Southern New Hampshire University

[Steven Clontz]

Here's what I suggest:

https://g4m.clontz.org/ch-collaboration.html

And if anything could be improved, I accept pull requests and issues myself! https://github.com/StevenClontz/github-for-mathematicians

[Adam Gilbert]

Hi Steven,

Thanks for this as well. I'm excited to read through more of this book!

Cheers,

--Adam

To view this discussion on the web visit https://groups.google.com/d/msgid/pretext-support/ec313e83-351e-4e78-bd20-1cd0e71c2212n%40googlegroups.com.