A while back a #devdiscuss post by @ThePraticalDev sparked a great discussion on the advice users have for getting the most out of Github. Either f...
For further actions, you may consider blocking this person and/or reporting abuse
I put my project's documentation on GitHub Pages and wrote scripts to assemble up-to-date docs in the
gh-pagesbranch whenever I cut a new version. It took some doing to get everything set up, but it's worked wonders for keeping the docs correct and current without being a major time sink.I'd like to know about your setup. Care to share in a dev.to article or an example repo where I can see it?
The repo is here; look in the build/ directory for the scripts themselves, and in the
scriptssection of package.json to see how they're wired up. The docs/ directory contains the "source" for the documentation.I might write up something more detailed soon but no promises -- it's a holiday week here :)
This is a really cool collection of tips :)
There's one thing I'd add, which is probably just an extension on the topic of Branches with respect to this tip: "Integrate Continuous Integration (CI) for building software."
I think it's very common to misunderstand Continuous Integration to mean "run automated tests on every commit to the master/production branch". Which, in a trunk-based-development environment is a partially complete definition - you definitely want to do that, but there's a lot more to it.
However when utilising git branches, it's important to execute your CI pipeline against all branches for every commit they receive. This ensures that your branches that, from the moment of their creation are slowly slipping away from master, are kept in line by being subject to the same, continuous, scrutiny. This commonly includes performing a merge with master in the CI agent to verify everything hangs together nicely.
This goes hand in hand with rebasing against master constantly.
Doing these two things means that merging back into master becomes super boring. You submit a PR, potentially for a code review, and then everyone feels comfortable about hitting merge because they know the branch plays nicely with master.
Waiting until the merge into master to verify that everything works together just kills your feedback loop. It could take you days to discover a regression that could have been identified in the first commit.
I've also found that businesses respond interestingly to this approach too, because when they have to pay for CI agents to run branch builds, they're suddenly really interested in keeping the number and lifetime of branches short. Which is something we should all want anyway ;)
Thank you for putting this together!
I used to use Gitflow. I don’t anymore because it’s a “hold” technology according to ThoughtWorks. Their reasoning is here: thoughtworks.com/radar/techniques/... and thoughtworks.com/radar/techniques/...
I do use branches though and pretty much do everything on a branch for the specific change/feature and then merge.
So, what is the alternative?
I don't use Gitflow, I use GitHub Flow most of the time (master is always deployable, feature/hotfix branches). I try not to let them live long, but you can't always constantly merge either into master because it is always deployable and you could have broken code at this point if you're merging daily.
I'd definitely like to know how ThoughtWorks handles this.
I'm not intending to hi-jack this conversation, but I felt I could provide some insight as a ThoughtWorker. I certainly don't speak for the organisation as a whole, but I can definitely share some thoughts.
I wrote a comment elsewhere in this discussion that partially addresses your question of "what is the alternative (to Gitflow)?". In general I'd say throw away the prescriptive rules about feature/hotfix/whatever branches, and stick to a simple branching strategy that aims to keep the branches as tightly integrated with master as possible (rebase constantly - literally with every commit), and as short lived as possible (think of days as a maximum unit of measurement for branch life. But hours would be better).
I'll preface the rest of this by saying that branching strategies work excellently for projects where there's low developer trust (like an open source project with random contributors). But if you've got a team of folks that you trust working on a product, the following may be useful.
On a more macro level, ThoughtWorks strongly favours Trunk Based Development over any branching strategy in most cases. The ultimate aim of TBD being that every commit made into a repository should be production ready. If a commit causes your CI pipeline to fail, work stops until it starts passing again.
Sounds like a pain in the ass at first. But committing constantly to master and having your code automatically verified in minutes means that if you've introduced a breaking change you know about it straight away - not a few days later when you merge your branch into master. This greatly reduces this risk of entering "merge hell", or just battling odd bugs after a "big-bang" merge.
You raise a very good point about not being able to merge with master frequently because of potentially broken code in your branch/commits. Luckily, we have feature toggles for that. Feature toggles allow us to deploy unfinished work into production, with the work itself being turned off and not available to your end users.
Your tests can still exercise your new code by turning the feature on in the test suite and doing whatever they want. And an added bonus is, that when it comes time to "release" your new feature, all you've got to do is change a boolean flag to true and you're off to the races.
If your new feature breaks stuff. Just turn it back off. No big, scary, patch to write. No panic. Nice and easy. And once your new feature is stable, remove all of the toggles in your codebase - It helps to think of feature toggles like branches in the sense that you should get rid of them as soon as possible after releasing a feature. Stale feature toggles are the worst.
I'd really highly recommend you give TBD a go. Even if it's just in a small side-project to get a feel for what it's like. To get started all you really need is a git repo, a CI tool (like CircleCI or Travis) and a simple, key-value, configuration file for your feature toggles.
Minor niggle, but catching potential merge issues early isn't a function of your branching strategy and is easy to do without adopting TBD. Just build every branch, and merge in the trunk before you do anything else. If you've introduced a conflict or broken a test someone else wrote in the interim, you'll know about it right after you push. If you wait on testing the merge until you're ready to integrate, you could have problems across multiple commits whether your branch has been alive for hours or days.
Absolutely, you're right on the money here. I addressed this in my other comment, but it's good to surface this point in this thread too.
I love this list. Looking forward to seeing any additional wisdom folks might have in these comments.
Nice article :)
My suggestion would be, if your open source project has > 1 people working on it or using it, it's time to start thinking about a code of conduct. It's much easier to lay down some ground rules when you've got five users rather than five thousand, and it sets the tone for the community going forward.
GitHub makes this really easy now!
Thank you so much for sharing this!
I've been wondering how to step up my Git game for a while and this is one hell of a good start 🏋️
Thank you for the great article! :)
I'm glad that you explicitly pointed out not posting secrets! One thing I'd like to add is never even commit private keys/API keys/certificates/secrets, even if it is in a random local branch. If that commit is ever pushed to the remote repository on GitHub (even if the secret was deleted in future commits) a site crawler could find it in your commit log and start utilizing it.
Nice article!
I advise you to put some example of branching model and how to make a code review.
I think that an article about how to make a good code review can be very helpful for many developers and It could be a second article related to your.
I think that sounds like a great post on its own, you should write it 😊
When contributing to open source, look to see if the repo has a
CONTRIBUTING.mdfile for more of an in-depth guide to how they handle accepting code.Great summary of tips, Kim! I already follow most of these, but the ones I don't yet follow, I'll be implementing.
I highly endorse Chris Beams's guide on How to Write a Git Commit. I try to follow his guidelines myself and share them with my team regularly.