How can avoid I merge conflicts on an interactive coding tutorial for beginners?

Question

I am working on a JavaScript tutorial series for someone who has no experience coding.

The format of the series is that it is a public Github repo. Each lesson is a README.md markdown document, and ends with an exercise. The exercise is usually some Jest tests that I've written, and the student needs to implement some functions to make the tests pass.

Also, all of the code examples I give in the readme, are contained in a index.js file (basically me making sure the syntax is correct, and that the output is correct), and I encourage the students to play around with it themselves.

You can see the series here.

One of the issues I've run into though, is that as this series is a work in progress (basically, I write the lesson and exercise, and my wife goes through it, and I get feedback on things I might have missed), I can easily push updates to the publish repo, but if the student has implemented the functions for the exercise, or played around with the index.js, and they do a simple git pull they'll get merge conflicts.

Now this is a beginner JavaScript course, not a course about using git. Basically the level of git usage I expect a student to have is to be able to clone the repo in the first place, and to be able to run 'git pull' to receive updates.

The course is a introductory to using the terminal - I also get them to navigate to the project, and run commands like yarn and yarn start.

Teaching them to resolve merge conflicts seems like a distraction and a bridge too far.

So the question is - what's the best way I can make updates to the course and have the student receive them, while keeping things simple and not getting into teaching git.

Some thoughts I've had:

• Add an 'update' script, that runs something like git checkout -- . && git pull - This would remove all of their changes.
  • The problem with this solution is that it removes all of their changes. People often like to look back on code they're written to see how it works.
• Add an 'update' script that runs something like git pull origin master -X theirs - This won't cause merge conflicts, but the automatic merge could potentially break things and lead to confusion.
• Add a 'prepare-lesson' script that copies all of the lesson code into a git ignored folder. The student can then play around in that folder and it won't be affected by incoming changes.
  • This kind of has the same problem as the first option - if they need to run 'prepare-lesson' after each update, this will clobber their changess.
  • Actually a good workaround is that each 'prepare-lesson' will copy into a new folder, so their old changes will in 'prepared-lesson-1' and the new changes will be in 'prepared-lesson-2',
• A similar approach might be that you have an 'update' script that is going to run git checkout -- . but before it does, it archives their changes to a git ignored folder.

Any suggestions or thoughts for solving this?

Answer 1

Structure your code differently. Have your main code work as a framework for what they are doing -> have a ToImplement class(es) in a seperate file which you will refrence in tests (maybe not even directly, you could still run tests against the index.js stuff). The class under test can have some public methods or you can make students add them, as the tests will fail otherwise. You can then mess with index.js if you miss anything and they could then just pull.

If you have some code already implemented for them to use, keep it in a seperate file and make them import it or import it yourself for them, but you have to keep a clear teacher/student seperation.

If they fool around with your code for some reason, have a checkout script for your files, and I think that will solve most of your issues.

Answer 2

Your lessons are simple and literal, and don't seem to involve confusing the student with a bunch of things that are not really part of programming with javascript.

The first thing that comes to mind for me seems like a whole lot of work for limited gain, but here it is...

Structure

Each student creates their own repo for the course. That repo does not contain the course source code.

• You can still offer them a git repo to clone to get started, but it is not your development repo.

• It's only a base blank project that contains a starting folder structure and refers to your course and tools as dependencies.

• They actually install your course via yarn commands, not by cloning the Git repo.

• Your course is a library and tools the student's project(s) refer to.

• The student's repo is entirely their own and is never updated with your source code changes via Git pull.

WorkFlow

So now you have a student with an empty repo and dependencies on your tools and libraries.

When a student starts a lesson, they run a yarn command to create the folder and copy the code for the lesson into that folder in their course repo.

Your repo is not upstream to theirs. Your changes never merge with theirs.

Let's say the student has done the first lesson, is part way through the second and has not started the third.

And you release an update to the course...

What happens to students depends how you defined the dependency on your course and tools.

• You could have your course and tools automatically upgraded the next time they run one of your commands.

• You could alert the student and let them decide when to upgrade.

But when they do upgrade it has no effect on their code in the lessons they have already started. That code is already copied and will never take a merge from your repo.

In our example:

Lesson 1 and 2 remain unchanged. Lesson 3 will use the new version when the student starts it.

If there is library code shared between lessons, it's up to you to make sure changes to that code are non-breaking to lesson code from previous releases, or to use some scheme such as semver to keep older lesson code pointing at older library code while newer lesson code uses newer library code.

Updating Lessons The Student Already Started

So far we have only defined a way to give them newer versions of lessons they have not started. But we have eliminated merge conflicts from your upstream repo.

What if you want a student to be able to upgrade lessons they are still working on, e.g. to fix a bug?

Some things can now be fixed with no effect on student code. For example...

• Fixing your library the student code uses.

• Fixing a static asset that student code refers to, such as a base css package or an image.

• You have to insure these are non-breaking changes for existing student projects.

• You can ship these fixes with no concern for merge conflicts.

Some changes are breaking changes. You should use semver or something like it to make these distinctions. A student may have two or three versions of one of your libraries so that older and newer lessons still work.

Changes To Lessons Already Started

You could go far with the rule of never trying to upgrade a student lesson that is already started.

• Offer students the option to restart the lesson in a new folder with your newer code, possibly keeping the old version in its folder.

• If the student has already completed the lesson they may have little interest in upgrading it. And you should not have to spend time on fixing problems that arise from that upgrade.

I would think hard and look for feedback from students before trying to upgrade their code, because even if successful it can be confusing.

But it's not impossible. For example...

• Static assets you copied into their lesson folder could be replaced.

• You could write upgrade / patch procedures to upgrade lessons when the changes are suited to that.

These things are very much case by case and may make sense in some cases but not others.

Students also always have the option of starting a lesson again with the new code and copying their code into the new folder, but making changes as necessary.

Clever students who have a good differences / merge tool could probably do that very quickly. And it's a very relevant skill for professional development.