Help with documentation what behavior is expected in Github for new users

[ericvd-ucb]

Hi I am helping to support the UC Berkeley Datahub - a large Jupyterhub with dozens of classes and 1000s of users. The main way that we deploy curricular materials is to us nbgitpuller to pull in materials. I do a lot of training new users ( faculty or student staff) to use Nbgitpuller

One chronic issue is that new users will 1) use an Nbgitpuller link once and 2) make a certain type of change in the source repo that 3) breaks the nbgitpuller when the user uses the link again to pull in more materials. 4) sending a particularly ominous and discouraging page of failed gitness

I would like help to document what is acceptable behavior in Step 2, and what causes problems.

• many existing classes have safe workflows that iteratively add to the source repo with no problems
• my understanding is that the problems usually come from changing the structure of the repo somehow, but there are multiple reasons something might cause problems

Apologies that I don't have a good example to reproduce these errors, because they are usually particular to an individual user

Outcomes:?

• documentation for new users to understand nbgitpuller safe behaviors - Happy to help with this / not sure where
• potentially changing warnings so that something more helpful and less ominous is communicated to users?

@yuvipanda

[welcome[bot]]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively. You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! :wave:
Welcome to the Jupyter community! :tada:

[yuvipanda]

Thanks for opening this, @ericvd-ucb!

I've opened #169 to start documenting some of these best practices. There are some very basic ones there right now, and we'll add more as we go. Do you have an example of directory changes causing pulling issues? That sounds very plausible! We can both debug those, and warn people away from that in the best practices.

Separate from that, we should:

1. Make the error page less scary. Right now, it's a python traceback - not even the failed git command. We should fix that.
2. There should be a 'troubleshooting' page, similar to best practices, to help folks debug common issues that can't be automatically fixed. For example, simply suggesting they rename the directory (https://xkcd.com/1597/) and click the link again might help a lot of people