Auditing Development Guidelines in GitHub Repositories
•Download as PPTX, PDF•
1 like•742 views
If your organisation has hundreds of code repositories you probably have some guidelines for them: how they are documented, how branches are protected, whether direct commits to master branch are allowed or only PRs should be used and all PRs should be reviewed, whether tests are run and code coverage is reported to PRs, etc. Making sure that those guidelines are followed is a difficult task - even if all team members agree to do so, sometimes we simply forget or don't have time to implement the necessary changes. Once we've agreed on our development guidelines, I was looking for a tool to automate such auditing for our team, so that in the same way as eslint can be used for testing code guidelines based on the rules, we could use this tool to audit our repositories in GitHub organisations. I couldn't find one so I created it. Meet gh-lint - a rule-based command-line utility that audits all your GitHub repositories generating results in TAP (Test Anything Protocol) format that can be consumed by tap-github-issues reporter that can create, update and close issues in github repositories.
Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Similar to Auditing Development Guidelines in GitHub Repositories
Similar to Auditing Development Guidelines in GitHub Repositories (20)
Recently uploaded
Recently uploaded (20)
Auditing Development Guidelines in GitHub Repositories
- 1. Development Guidelines Evgeny Poberezkin @epoberezkin #fullstackcon
- 3. Which guidelines? 1. Code 2. Tests 3. Process
- 4. Code
- 5. History of guidelinesIt is good, as long as it works
- 7. ESLint: you decide good and bad
- 8. Tests
- 12. Process
- 13. Change process
- 14. Semantic commits chore: add Oyster build script docs: explain hat wobble feat: add beta sequence fix: remove broken confirmation message refactor: share logic between 4d3d3d3 and flarhgunnstow style: convert tabs to spaces test: ensure Tayne retains clothing
- 15. How do we know if we follow guidelines?
- 16. Existing tools? • Only validates names of commits, PRs, issues • Not extensible • Not open source • Great promise • Doesn't work
- 17. Demo Validate repositories against rules: https://github.com/MailOnline/gh-lint Manage issues based on TAP report: https://github.com/MailOnline/tap-github-issues Sample gh-lint config: https://github.com/MailOnline/gh-lint-demo
Editor's Notes
- I am Evgeny Poberezkin. I work as the Head of Development at MailOnline – one of the largest news websites better known as Daily Mail. I work with 25 excellent software developers and we do very cool stuff there. Previously I’ve been extremely lucky to have the opportunity to build the second generation of MailOnline content management system. We’re now about to kick off another exciting JavaScript project and we’d be very happy to hire several experienced developers.
- So, let's see, who here uses any guidelines? For example, can you raise a hand if you do static code analysis with eslint or some other tool? Now, do you measure code coverage? Do you follow git flow making all changes via PRs that are reviewed by your colleagues? Do you have requirements for commit names (semantic commits)? Why do we need guidelines? There are many reasons for them. We may believe that they increase productivity. We work faster as we don't have to make decisions about many things. Or we may believe that they make code more maintainable. As one of our engineers said, "everybody's code becomes my code". Or we may believe that they increase stability and quality – the code is more likely to work all the time, every time. The bottom line is: they make us feel better about the work we do and they help us communicate
- So, what groups of guidelines we are talking about? Firstly, the guidelines on how we write code. Tabs or spaces? If spaces, 2 or 4 spaces? Space or no space after function name? Etc. etc. – a million of other equally important things Secondly, the guidelines on how we write tests and measure code coverage. Thirdly, the guidelines covering our development process: PR or not PR? Commit names? etc. Having all these rules is very important – if nothing else they make us feel very professional.
- I believe that in the good old days there was one success criteria applied to code: it is good, as long as it works and it is fast, as computer usage was very expensive. There were no other guidelines. I hope.
- But then this man came and split our hearts and minds irreversibly, taking away our freedom. He said: "there are bad parts in your code, I will tell you what they are. You should remove them, even if your code works." And he gave us a tool – jslint to guide us towards a better code, as he defined it.
- But then Nicholas Zakas brought us a bit of our freedom back. He said: "there are bad parts in your code indeed, but only you can decide what is good and what is bad" And he gave us a tool – eslint to guide us towards a better code, as we defined it. Now we have tons of fun creating rules for all possible cases and making decisions about how we write code and which set of rules we use. But at least within the project we are consistent. Remember, "everybody's code is my code"?
- Secondly, the tests. That is a big and controversial question. TD or not TD?
- There are some strong and famous advocates of "test-first" ideology. On the left here we have Kent Beck, who created TDD. Or "rediscovered", as he says himself. On the right here we have Uncle Bob, who preaches and teaches TDD at any opportunity.
- But quite a few leading open source developers rejected TDD. The creator of RoR and the founder of Basecamp David Hansson wrote the article "TDD is dead. Long live testing". He wrote: "Test-first fundamentalism is like abstinence-only sex ed[ucation]: An unrealistic, ineffective morality campaign for self-loathing and shaming."
- I wrote a blog post summarising my thoughts about TDD and how test coverage can be used to drive the development instead. "Right or wrong, this is closer to how I actually work most of the time." "I don't fully agree with this, but this looks very much like my preferred approach"
- Thirdly, the development process
- Do we use PRs and mandatory reviews or do we commit directly to master branch? I've heard equally strong arguments for both approaches and practised both. These days, it's PRs. Mostly.
- Do we allow anything in commit names or we have some requirements for them? E.g. lots of people use "semantic commits" but I am yet to see any hard evidence whether they increase productivity or help in any other way. Some teams require that Github or Jira tickets are included in the commit message.
- If we agree to follow some guidelines, how do we know if we follow them? At MailOnline we have nearly 900 repositories, 200 of them are changed in a month so trying to answer this question without some kind of tool is impossible.
- I've found only two things