cotech/website

Clarify process for making changes to code in the repository

floehopper opened this issue · 8 comments

floehopper commented

Now that the dev branch is being automatically deployed to the dev version of the website and the master branch is being automatically deployed to the production version of the website, it would be good to agree a process for making changes to the code.

When I was looking to merge #44 I was a bit surprised to find a bunch of commits in the dev branch which hadn't been merged to master and which had not come via a PR. I ended up cherry-picking the one commit from the PR into dev to check it didn't break anything, before then merging the PR into master, in order to avoid including the "extra" commits in dev. This doesn't seem ideal.

I think I would've preferred to have rebased the PR branch against dev and then merged the PR branch into dev, before finally merging the PR branch into master. However, this would've also included the other commits in the dev branch which I had no knowledge of.

Does anyone have a clear idea how people should make changes to the code? Is it OK to make changes directly to the dev and/or master branch, or should we always use a pull request? How should changes be moved into dev and into master? How long can commits sit in dev before they are either merged to master or removed or reverted? If commits are left "sitting" in dev, they can act as a block to others wanting to deploy changes.

It would be good to have clarity on this and explain the process in a CONTRIBUTING.md file.

chriscroome commented

I agree that a CONTRIBUTING.md file that outlines the agreed processes would be ideal, @floehopper would you like to suggest some text for this?

It is easy for me to set up new copies of the site that track additional branches if that would help — if anyone needs a whatever.coops.tech site setting to track a branch just let me know.

floehopper commented

I'm not really sure what the best process is in this case - I've never worked on a project with two branches setup to auto-deploy before, nor on a Wordpress project. Perhaps someone who has worked like this before can suggest the best way for this to work with git and GitHub...?

Some questions:

  • Is it OK to commit directly to dev or master i.e. not via a PR?
  • Is it OK to leave commits in dev for more than a few minutes without merging to master or reverting?
  • Can you merge your own PRs? Or should you always get someone else to check them?
  • Do changes always have to be merged into dev before they are merged into master or can they be merged directly into master?

Maybe I'm worrying unnecessarily about all this, but if the website is going to be a genuinely collaborative open-source project, I think it would be useful to make this stuff clear.

One of the key questions in all the above points is how easy should it be to make a changes versus how much checking do we want to happen before anything gets deployed to production.

floehopper commented

To keep things simple, we could say something like the following:

  1. No commits directly to dev or master - only via merging PRs.
  2. PRs are merged into dev temporarily for testing and then either merged into master or reverted.
  3. You should always get someone else to merge your PR i.e. to double-check your work, ideally checking it on the dev version of the site.
  4. A PR branch is merged into dev using a non-fast-forward merge to mirror what GitHub's big green "Merge" button does when merging the PR branch to master. Ideally PR branches should be rebased against master before merging.

However, others may see all this a too restrictive.

chriscroome commented

@floehopper I think that is fine as long as we also offer to setup sites tracking other branches for people for whom that is too complicated and restrictive, for example I could create a harry.dev.coops.tech copy of the site to track the harry-dev branch for things he is working on if needs be...

floehopper commented

@chriscroome:

Can I ask what git command(s) the cron job uses to "sync" a branch? Is the cron job code publicly visible somewhere. The reason I ask is because I'd like to understand whether there are implications of re-writing history on the dev branch.

Also is there any significant difference between the way the app is run in the Docker-generated development environment versus the production environment? i.e. if I see something working in my development environment, is there really any need to deploy to the dev box?

harryrobbins commented

Hi there - apologies if I've been doing it wrong! I don't do grown up development at Outlandish and don't really get the whole git-flow thing - happy to follow guidance though. I assumed the sensible thing was to test stuff locally, deploy to dev in order to check it worked on the server and create a PR to master. Happy to follow your lead/guidelines.

We've got some new ultra-fancy docker-based CI pipeline thing in the works I believe - maybe we can do a demo at Wortley Hall.

  • ❤️1
chriscroome commented

I assumed the sensible thing was to test stuff locally, deploy to dev in order to check it worked on the server and create a PR to master.

That works for me, if we replace it with something more complicated we should make sure everybody understands it and it doesn't result in less people being able to work on the code base.

floehopper commented

It seems as if everyone else is happy, so I'm going to close this issue.