This is a continuation of Getting Started With DevOps, Part 1.
Documentation
Let’s air out all of our dirty laundry. I know, just reading the word makes some people cringe. Documentation is not for the doers.
Why should I document how to do something if I already know how to do it?
Documentation is the fingerprints of those that came before you. Sure, one type of documentation is bootstrapping a development environment, but truthfully, documentation happens in many forms.
If you remember in my first part, I point out that the more thought you take out of development, the more your brain can focus on other, more important, stuff.
Here are some example forms of documentation:
- How to setup development environment
- Error logs and anything else that makes the application sing
- Restful API endpoint structure, parameters, and response objects
- Generally anything anyone would benefit from knowing
If you look at it this way, you (and your team) only know what you document.
Have a new guy/girl? Have them test your documentation. If they find any workarounds or little nuances that go along with developer setup, it’s their job to update the documentation.
Single Source of Truth, Decentralized
I love the MarkDown language. It’s easy to use. I don’t have to take my hands off of the keyboard, and it’s human-readable even in raw form.
Best of all, because it’s plaintext…guess what manages plain text magically? You guessed it, Git does!
That’s right, gumshoes! Sure, you can store your documentation in a Wiki, but where is a place that all devs should have access to? The source code!
What I like about this method is that your documentation is maintained with the source code. For a private team, this is very useful and very easy to maintain. It will always live with the source code no matter what tool you use to host your code (Github, Bitbucket, etc).
For public projects, it still makes sense to have a Wiki or some form of other hosted documentation; however, make sure other aspects of the project are also documented.
When You Build It
It’s one thing to build it on your machine, and you should, but you should also use a build tool like Jenkins, Travis CI, or Circle CI.
The main reason? It’s clean. It doesn’t have all of the older versions of 80 NPM packages you downloaded to try.
In case you’re wondering, CI stands for Continuous Integration. It’s the first half of CI/CD. The second have is Continuous Delivery.
CI, to me, is where it all comes together. Your CI tool should be a well-tuned machine. It should stand up your development environment in minutes, run your tests, build your application, tag the version, and deploy the artifact to a repository.
Setting up your CI tool should mimic the documentation you wrote to get your development environment going. What tools did you have to install on the command line? What permissions did you need to set and forget on files and folders?
All of those one-off things you did months ago and forgot about after you’re environment has been setup? You need those.
Your CI tool, if done right, should literally enable you to pull down your repository without setting up your environment. Yes, you should be able to clone your repo, write code in a basic editor like Notepad, and push your code. Your CI should handle the rest.
Realistically, that implies a lot of risk writing code in the aforementioned manner, but if you have the proper checks and balances in play and build is successful, ship that code!
https://medium.com/media/9ce89463e75d7ea78029937e2b6f94f5/href
Let’s recap.
Your CI tool should
- stand up your development environment
- lint your code
- run your unit tests, save your integration tests for later
- output a code coverage report
- tag a release
- deploy the release artifact to a repository
Once you have your release artifact in your repository, let’s deploy it to a test environment and…test it some more! It’s at this point we could run our integration tests since we’re in a live environment. You could also do some manual testing and basic smoke tests.
Polish It Pretty
It’s high-time for your build to graduate! If you have a testing environment, you should also have an environment for QA. Builds here should be polished and pretty so QA can do their thing. This is where automation can happen for end-2-end testing and exploratory testing can happen with humans.
Once you have your pretty polished package and all of your committed features match the accepted criteria, it’s time to send your build off to Production.
Thank You
By now, you should have an idea about getting your application into the hands of another human (or machine) who didn’t compose it to use it.
Beyond this, you get into the realm of application lifecycle and how to manage your baby in the real world with real loads and network shenanigans.
I hope you’ve enjoyed this short series.
Latest comments (0)