Hi Robin, Quite an interesting question you posted. I can easily compare what your problem is with my experience with my proof readers during my thesis. You get correction of typos, suggestions of how to rephrase certain text, and questions of what is the meaning of your text. Probably the last two were the most important ones for me, as they were concerned with the meaning of the text, and they could be easily misinterpreted. (I don't know whether the native English speaker suffer of that too much though). I didn't have a github then and I didn't imagine a tool like github would solve my problems and ease my writing and learning.
So, going back to your example, from the approaches that you suggest I would mix 2 and 3. Some things (those similar to typos or style and formatting) I could do all in a pull-request. There's no "meaning" in these and it should be straight forward to notice just by a diff. Larger changes - like re-factorisation - would do in Pull requests by blocks. The problem with separating that into many commits is that I believe that each "commit" should be for running versions. I would not feel happy commit half changes that results in broken code. Each commit should be the smaller change of code related with a particular purpose but everywhere. This is my opinion though.. I can see why you would like to commit often even when the code is broken... but I try to avoid that as much as I can. Then there's the "meaning" changes, the ones you may believe what the author wanted to do but you are not 100% sure why was written in certain way. There I would write inline comment in the code and discuss it there (or as an issue). Can this be done better in a way that the student learn from the changes? I don't know. I thing the ultimate message is to learn how to review, as you learn from reviewing a lot more than writing in solitude. Promoting discussion more than imposing changes and so far this is what makes for me the concept of Pull Requests so wonderful. Cheers, David On 23 July 2016 at 21:40, Robin Wilson <[email protected]> wrote: > Hi, > > I'm aware that you may have read the subject line and thought "use git!" - > but I think there's a bit more to this question than that... > > As part of some small-group programming teaching, I'm trying to show some > examples of development of code over time, as the code is gradually > refactored, made more generically-applicable and generally improved in > quality. I'm trying to work out the best tool or approach to use to show > these changes with annotations about why each change was performed. > Obviously when teaching face-to-face I can go through this interactively > with the students - but some changes to real-world code are too large to do > live - and students often seem to find these sorts of discussions a bit > overwhelming, and want to refer back to the changes *and *reasoning later > (or they may want to look at other examples I've given them). > > For context, I'm sometimes doing this with little demonstration scripts > that I've written, sometimes with real-world code from other projects, and > sometimes with code that some of the students themselves have written. > > Approaches that I've tried: > > 1. Making all of the changes to the code and providing a separate document > with an ordered list of what I've changed and why. > (Simple and low-tech, but often difficult for the students to visualise > each change) > > 2. The same as above but committing between each entry in the list. > (Allows them to step through git commits if they want, and to get back to > how the code was after each individual change - but many of the students > struggle to do this effectively in git) > > 3. The same as above, but using Github's line comments feature to put > comments at specific locations in the code. > (Allows annotations at specific locations in the code, but rather clunky > to step through the full diff view of commits in order using Github's UI) > > I suspect any solution will involve some sort of version control system > used in some way (although I'm not sure that standard diffs are quite the > best way to represent changes for this particular use-case), but possibly > with a different interface on it. > > Is this a problem anyone else has faced in their teaching? Can you suggest > any tools or approaches that might make this easier - for both the teacher > and students? > > Thanks, > > Robin > > > _______________________________________________ > Discuss mailing list > [email protected] > http://lists.software-carpentry.org/listinfo/discuss >
_______________________________________________ Discuss mailing list [email protected] http://lists.software-carpentry.org/listinfo/discuss
