spacetelescope / notebooks

Content in this repository is not maintained and is actively being migrated to other repos.
https://spacetelescope.github.io/notebooks/
BSD 3-Clause "New" or "Revised" License
217 stars 163 forks source link

Contributing guide needs a better warning about Clearing Notebook Cells and history. #18

Open mustaric opened 5 years ago

mustaric commented 5 years ago

You should note that you need to both clear the notebook cells and SAVE the notebook again before pushing. I had cleared the cells and checked in before the Jupyter autosave had kicked in. So I was quite confused when Travis said I had executed cells.

Given this is such a strict and, somewhat unusual, requirement for creating these notebooks, these requirements need to be stated more loudly. Also instructions on how to purge your history for those who do accidentally check in a run notebooks.

eteq commented 5 years ago

Agreed this should be added, @mustaric. Where do you think you'd be most likely to see this and want to find it? The style guide, or a README in this repo?

I should add, though: in my experience, documentation like this is often better written by those who encounter the problem because they're most likely to be coming from the perspective of a new user (e.g. it never occurred to me to mention the save thing because I've done it too much to realize it's a stumbling block). So I'd welcome a Pull Request from you that addresses at least the "save" part of this if you have time. If not, I'll try to get to it when I can - either way I'll aim to write up some instructions on the git steps required for the second part of your suggestion.