Auditing Development Guidelines in GitHub Repositories
Download as PPTX, PDF1 like751 views
The document outlines development guidelines by Evgeny Poberezkin, emphasizing the importance of having structured code, tests, and processes for efficiency and quality. It discusses the use of tools for validating adherence to these guidelines, highlighting existing limitations and providing resources for demo configurations. The presentation encourages best practices such as semantic commits and effective issue management.
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
- #2: 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.
- #3: 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
- #4: 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.
- #6: 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.
- #7: 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.
- #8: 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"?
- #9: Secondly, the tests. That is a big and controversial question. TD or not TD?
- #10: 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.
- #11: 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."
- #12: 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"
- #13: Thirdly, the development process
- #14: 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.
- #15: 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.
- #16: 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.
- #17: I've found only two things