The neatest feature of #git I didn’t know was there

I have been using git for several years now. But like any other tool, you don’t REALLY know all its power without using it in the craziest situations. I’ve just discovered a core aspect of git that totally drives me nuts given what it can do!!!

Git is a distributed version control system, right? Those of us using it with github are probably well aware of pull requests, making local commits, and doing various day-to-day operations. But something I didn’t understand until I had to process a pull request from the Spring community was exactly WHAT a git commit was.

Git commits are hashed. The don’t use counters, because they must be unique across any machine. You can’t depend on the counters working correctly. Instead, the idea is that people can develop separately, in another repository, and then submit pull requests to make a contribution. I as the developer can then merge your pull request. Sounds great, right? But did you just skim over that that sentence, “merge your pull request“.

What are we doing when we “merge your pull request“? It typically means we are pulling changes from your forked clone to mine, but once you realize that there is zero requirement for a relationship between your fork and mine, you discover that commits can be pulled into ANY repo and branch.

For Spring’s getting started guides, we have a central repo where people can write entirely new guides, and submit them as pull requests. But we don’t merge them there. Instead, we create a whole new repo and pull in the commits there. And we do that after you have made your contribution. If you look at those commits, it will appear as if everything was created, developed, and published there. But it wasn’t.

For any guide, the tentative author first creates a draft for a guide. Authors are encouraged to create a fork of that central repo and then start making their edits. At that point, everything can be pushed up to a branch. The author crafts a pull request. From there, we could merge back to the original master, but we don’t want to. Instead, we want each guide in a separate repo to suitably manage each guide separately. This lets us take all of the author’s handiwork, and put in that separate repo.

Basically, commits are self contained. If you develop something on one branch, and I development on another branch, it’s possible to merge both of these efforts into a third branch in a totally separate repository. And it doesn’t matter if one is a forked clone of the other. Clean things up, and we can turn this all into a pull request back to the original master. Or it can go elsewhere.

The point is, breaking up work into commits, sharing them with others on branches, whether on your fork or not, you can keep things nicely segmented. Then it becomes easy to hammer out issues and fold things together. And the side effect is that ALL commits retain their history, status, and who wrote what. You can squash things if you wish, whereupon some of the history is flattened. But this type of flexibility is incomprehensible when using something like subversion.

Why git + @Dropbox + @Asciidoctor + @Crashplan => perfect environment for writing /cc @PacktPub

packt-logoOne tidbit that Packt sends its authors is strong advice to BACK UP YOUR WORK. It will happen. So don’t get caught with no back up of your efforts.

As I being working on chapter four of Learning Spring Boot, I can tell you that I got this one covered in spades. I’m a firm believer in version control. I use git to manage my manuscript, code, and everything else. Mind you, This way, I can always back up to a previous version of anything and either recover something or use it to respond to feedback. In general, version control is protection from my own edits.

The git repository for my manuscript lives inside my Dropbox folder. That way, all my work is immediately visible on my phone, my wife’s tablet, and any other computer I have linked. To top things off, it essentially backs everything up to a remote location. This is a way to back up against hardware failure.

I also have a Crashplan account. I have the maximum plan, which means ALL my computers (max is 12 machines) are backed up with unlimited data volume and unlimited versions. I can find older versions of files if need be, and if I can’t locate via git. I have actually rebuilt my laptop twice in the past four years, and Crashplan was the key to recovering personal data.

To top things off, using Asciidoctor to write my manuscript has been fantastic. I don’t focus on layout, spacing, and other boring word processor stuff. I have focused on content. Quickly rendering a web page of a given chapter and proofing it in my browser is GREAT. After all that, I then open it up inside LibreOffice, and make sure I haven’t broken any margins. I’m still having to hammer out some issues with an editor, but I’m sure this investment will pay off in the long run.

Why did I write this? One of my followers spotted some new product from Amazon that appeared to be a collaborative tool. He or she was suggesting I take a peek. I quickly spotted the price tag of $5/user/month. No need! For writing a small book, all these tools are enough. The only thing I’m paying for is Crashplan. The rest of the tools are free.

When I think about doing the same thing fifteen years ago, I cringe at what the state of the art was back then. To truly embrace open source back then and pursue an open source only lifestyle would have been nigh impossible. But today? No one thinks twice about using free software tools to get real things accomplished.

Chapter 3 of “Learning #SpringBoot” wrapping up nicely.

learning-spring-boot-ch3I just typed my last sentence for Chapter 3 – Debugging and Managing Your App. It’s fun because this chapter knits together a handful of concepts that are sort of spread across the reference docs. In other words, there are several tools at your disposal provide by Spring Boot, but it might not seem obvious if you’re new to using it.

This chapter dives into Boot’s auto-configuration report, creating customized health checks, info, and other things. And we also create some custom CRaSH commands. It’s all pulled together in the context of debugging and maintaining production apps. These are some pretty nifty tools I wish I had access to five years ago at my old job! Hopefully, others will be able to put these features to use immediately.

When it comes to writing, this is the step where I then go to the top, and skim over it, trying to tighten things up. I like this, because it’s not due until next Saturday. I can proof it, clean it up a little, make sure it flows, and then send it off to my reviewers. Ultimately, I can start writing Chapter 4 – Data Access with Spring Boot ahead of schedule. I always like to stay ahead of the deadlines, and feel really good about that.

A new project in my spare time…helping my nephew create games with #Python and #Pygame

My nephew expressed interest last year in creating games and programs on his computer. I bought him a super cool book, Making Games with Python and Pygame. He’s been busy with other things, but today I got a call from him asking how to set up Python.

I was driving so I couldn’t get very far. But the pure fact that his parents have a Mac made me smile. We could speak on the same wavelength. I promised to send a follow up email with some HOWTO steps.

The first thing I did was reach for Asciidoctor and start writing up a handful of steps to get started. I had to really dial up the thinking, because I wasn’t writing for a pro developer. I was writing for a kid that doesn’t know any of this.

I also decided to host it all at https://github.com/gregturn/so-you-want-to-learn-python as the place to manage everything. After getting that fixed up, I realized I could pipe the generated HTML into a gh-pages branch, and host the polished stuff at So You Want To Learn Python.

Should be enough to get the ball rolling. Waiting eagerly for a response!

Finding your voice when writing a technical book

learning-spring-boot-ch3Something that I have been polishing for some time is my writing voice. The voice is more than just words, grammar, and speaking in a me-to-you, versus us-with-us style. It’s the way we blend words and language together to provide our writing with a certain personality. One of the things that won me over before I got past page one of Killing Floor, the first Jack Reacher novel, was the voice.

In that page, the dialog was 1st person, coming from Reacher himself. It was calm, clear, and crazy. The man was being arrested. Why? Unknown. And yet, Reacher didn’t tremble a bit. He had no fear. Again, why? I would panic! On top of that, Reacher calmly moves such that no one ELSE in the diner is put at risk. What?!? I had a clue who he was, because I had seen the movie. But subtracting that, you DON’T know who he is, and this type of uncharacteristic reaction to three cops with loaded firearms made me hunger to turn the page. Again and again and again. The voice grabbed me and held onto me through the whole book. And to the next book. (I’m not on #10).

Since I started writing this blog six years ago, my writing style has matured. I have slowly found the way I want people to share the thoughts I am putting down. I want it to be fun and not a cold lecture. I want to invite people in, and hunger to read my next post. And my next one after that.

When I wrote my first book, Spring Python 1.1, I was new to the idea of writing a book. I struggled with being concise. Boiling ideas and concepts into simple, well crafted sentences. I wanted the reader to enjoy what they were seeing and be able to think of ways they could use the code to meet their own needs. I didn’t think much about my voice, but instead more about the content.

When I embarked upon writing Python Testing Cookbook, I was much more confident. I had a big vision of what I wanted to tackle, how I wanted to tackle it, and what was important to me. I also had a better sense of time management and what it took to get things done. And I had a clearer picture of Packt’s shortfalls that I needed to watch to make sure the release was top notch.gs-scheduling-tasks

So as I began writing Learning Spring Boot, I had much more creative energy. I had even launched a separate financial blog two years ago and reached a rhythm of blogging two posts/week. To top it off, last summer, two other devs and I had been tapped to write over fifty getting started guides. I spent all summer writing technical stuff. We worked hard to find a common voice the three of us could share with the intention we would spread it to others to decentralize the writing in the long run.

All that writing I felt had improved my writing on several fronts. I had more self confidence to write in the voice that I chose. I had also honed my blogging voice. I was interested in the long run of people being able to read my book, and then visit my blog, and find some familiar writings. Or the other way around. And I had learned how to write for different audiences with different voices.

Here’s a sample from chapter nine of Python Testing Cookbook:

Testing isn’t a cold, mechanical process. It’s an exciting, fiery area of development. Test bitten developers can’t wait to share it with others. If you look for ways to spread the fire of automated testing, eventually others will warm up to it and you will find yourself talking about new testing techniques together. –Greg L. Turnquist, Python Testing Cookbook, p.330

If you read Scheduling Tasks amongst Spring’s Getting Started guides, you won’t find this same voice. You’re not supposed to. You’re supposed to find an entire collection of guides with a somewhat uniform style that show you how to solve common problems quickly. Making these guides consistent, uniform, and simple took an arduous amount of effort.

But if you switch to reading this blog, you’ll find a different style entirely. It’s more personal, because this is my personal blog site. I want to write enticing articles that you’ll enjoy.

And in Learning Spring Boot, here’s a sneak peek of some of my prose from Chapter Two: Quick Start with Java:

For production-ready support, it’s nice that Actuator provides us handy data we can consume. The scripts we used to consume these metrics might seem a bit crude. But in the real world, we need tools that let us quickly try something out before investing in bigger, more complex, and often more expensive solutions.

If our manager wanted a quick read on the last twenty four hours of data, we could easily take `metrics.groovy` and adjust it to have a rolling time limit. We could then serve up the content using a little Spring MVC. Cash in on Spring MVC’s WebSocket support, and we could have the screens update dynamically. Program managers love eye candy, right?

There’s no telling what requirements we’ll get from sysadmins and managers. Spring Boot’s easy-to-consume endpoints provide us the tools we need in both our main application and the support tools we’ll build up to manage things. –Greg L. Turnquist, Learning Spring Boot

I am receiving feedback from a couple of my colleagues as well as an editor. I have to sift through this material and decide what is an undeniable improvement (faulty words, typos, bad grammar) vs. stylistic changes. And when it comes to stylistic changes, I have to figure out which things will improve my story and which things impede my voice. I want to polish my voice and nothing helps better than honest, objective feedback from others.

So if I’ve held your attention this far,  I hope that perhaps you are also thinking of writing. I wish you the best of luck, and never to be afraid of asserting yourself to define your own voice.

Chapter 3: “Debugging and Managing your #SpringBoot app” underway

learning-spring-boot-ch3Last Friday, I submitted the 1st draft for Chapter 2: Quick Start with Java. In that one, I walk through the detailed steps of crafting an app that scans for open issues against multiple GitHub repos using several Spring projects.

With that behind me, I am now diving into Chapter 3. In this chapter, I want to help any developer understand what Boot is doing, how it does it, and basically give them all the tools needed to debug and manage a Boot app.

Long ago, I remember Spring and it’s auto-wiring. This code was deemed by many as too magical, only good for toy apps, certainly not for production, and generally something that more of a trick than of real use. Today, that is no longer true. Instead, auto-wiring is recognized as a valid technique. I see it used all over the place including the app that runs http://spring.io.

I have been worried that Spring Boot might accidentally get dubbed as another form of magical code. The way it works is actually quite simple, once you understand it. Or shall I say, once I discovered how it worked last year, I sat down and quickly wrote up auto-configuration support JMS and RabbitMQ before I left the SpringOne conference. Heck, I even felt motivated to write a blog post!

So before anymore delving into what you CAN do with Spring Boot, I wanted to devote a chapter on how to debug apps and not get surprised or caught off guard.

Spring Boot has one tangled issue being worked on. There is no simple way to extract ALL the property settings or flatten out ALL the switches and flags of how Boot auto-configures things. In fact, other teams outside Spring and Pivotal are starting to create their own auto-configuration hooks as well.

You can get really far with the reference docs. But in my opinion, sooner or later, devs will have to look at the source code. My goal is to help decrypt that process and show how simple it really is.

Spring Data REST => HAL + meta-data /cc @springcentral #rest #hypermedia #alps

spring-data-rest-alpsGreetings Spring Community!

We are working on a new feature inside Spring Data REST: meta-data. When you are talking to RESTful backend over the wire, you might not know the details of the resources behind the URIs. This enhancement provides a way to dynamically serve up domain-specific meta-data to the clients.

If you’re interested, you can see a tiny example of what we’re working on.

The README at the site includes information about to check it out, run it, and interact with the hypermedia-powered, RESTful interface. It shows you how to leverage the meta-data to create new entries.

I need your help

Please feel free to visit the site and try it out. Anything missing? Something not clear? Feel free to either tweet me @gregturn, leave a comment on this blog post, or if you’re feeling bold enough, open a github issue against my TODO example.

Chapter 2′s first draft is roughed out

ch2_fodtLast night, I finished up the last bits of chapter 2′s first draft. I like to knock out a chapter in the rough and then go through it, applying bits of polish. For me, it’s always easier to polish something that already exists.

My biggest concern was the fact that Spring Boot keeps taking away space filling code! So instead of creating some boring toy app, I had to think up something bigger. I figured an app that scans open issues from multiple GitHub repositories (part my upcoming webinar on creating management apps with Spring Boot) would be good enough. Wrong!

This chapter’s demo app has become way too small! Ever hear of that? Our apps usually are too big, especially for the medium of print. I tried to fill up the allotted space with deploying to one of the fastest growing PaaS’s out there: Cloud Foundry. There are over thirty members of the Cloud Foundry Foundation, so showing how über easy it is to push your Boot app up to a cloud should eat up space, right.

Wrong again! Well this has forced me to roll up my sleeves and actually write some pragmatic support scripts that load the system down and gather metrics at the same time….using Spring Boot!

So after slaving away at creating useful code, deployed to a useful platform, with useful support, I figured any more content and this chapter would explode in practical density. I saved my last changes and decided its time to now go through and polish things up. There’s always an opportunity to add another chapter later on, right?

It’s nice to read through the manuscript and see if it flows. Am I going to fast? Too slow? Sometimes its a mix of both. Given that this will be THE first Spring Boot to hit the proverbial shelves, I want it to be a good reading experience. I also ponder what questions the reader might be thinking, and try to insert pull-outs answering them.

I’m also incredibly happy that I was able to get a functional Asciidoctor backend written AT THE SAME TIME. Don’t worry, I drink plenty of coffee in the morning to recover from my total lack of sleep. :)

Stay tuned for future developments!

The value of software communities is greater than ever

ch2_fodtAs I continue working on my new book, Learning Spring Boot, I have really noticed the value of communities today compared to when I became a professional software developer back in 1997.

Back then, there were news groups and mailing lists, but not the same indexing of EVERYTHING, no Google Groups (which just made searching/working with news groups MUCH easier), no panacea of discussion forums, and no proliferation of blog sites. These things existed, but you wouldn’t find so many, and so dedicated (like trying to write a query for your trade novel, one of my favorites). And open source hadn’t taken root like it has now. Your prospects of finding an open source project with a thriving community to serve your needs were MUCH less likely.

So how exactly did we survive without such a rich community? Sometimes I’m mystified. Back then, I would comb the book store for help. It also meant I had to hunker down and really go through code myself to figure stuff out. What’s that you say? You think that I’m whining about having to actually WORK back then? I worked then, and I work now. It’s just different.

Today, perhaps there are more people willing to help you get over a hump. Back then, getting help meant walking across my cubicle hallway and asking the right team guru questions. Over time, I would pick up my own set of skills and quirks. And others recognized that. Eventually others would come to me asking for assistance.

Back then, I knew someone that NEVER deleted emails. I didn’t comprehend such a concept. Today, I’m a tried-and-true believer in keeping everything. Knowledge is power, and having my entire history of communication available has been useful. In fact, when I finally moved my personal email off the telco provider I’d used for years, I searched for someone that could handle migrating all that email to my new account.

Today, it seems impossible to develop anything in a vacuum. I tap twitter, discussion forums, and other places. The latest incredibly powerful social tool for interacting, getting feedback, and making substantive progress if GitHub! Git is a powerful tool for version management, but you can’t realize its true value until you work on a community project with forks, issues to discuss things, and ultimately pull requests.

I launched my book writing endeavor by blogging and tweeting what I was up to. On my previous book, I got enough attention that I was able to shift off a tool that had fallen into disuse and pick something better. I even got quotes from project leads into my book.

This time, I attracted the attention of both Dan Allen, the project lead for Asciidoctor, as well as an editor from Packt Publishing. I am building a new Asciidoctor backend for Packt, and this might be the track that makes it mainstream. Dan quickly helped me get going on something that I couldn’t make heads or tails of when I read it by myself. If Packt bites at somehow making this backend an officially accepted medium, the lives of MANY future authors may be made simpler while also improving the content of future titles. (That applies to my own future writings!)

To paraphrase Hugh Williams, Pivotal’s new SVP, skills are fleeting. The knowledge you are using today will probably be totally replaced ten years from now. But what’s critical is judgment, ability to learn, and willingness to interact with others. And nothing serves that better than a strong community.

Goodbye #AsciiDoc, hello @Asciidoctor. Tnx @mojavelinux!

asciidoc_numbered_listI just got my last few tweaks into my Asciidoctor Packt backend. It was enough to drop the venerable AsciiDoc and replace it with Asciidoctor.

Most notably, I fixed the images so they would be centered, and text would not wrap around. I also centered the [[Layout]] note that always is placed below. It looks perfect!

I can say this: working with an asciidoctor backend is gobs simpler than that asciidoc backend. It was brittle, hard to decode, and most of the time I was editing a monolithic file. With asciidoctor backends, each logical fragment is split off into a separate file.

In each file, I was using slim, a very terse way of writing templates. Given that the output is FODT, i.e. XML, slim is pretty neat. You get to express XML structures without the overload of reading angled brackets or having to write the closing tag.

But none of this would have been possible without Dan Allen’s direct involvement. I tried to get started on my own, but it was a no-go until Dan stepped in and submitted a pull request with an initial cut of a backend along with some critical steps to use it. To top it off, we were able to work back and forth, either through more pull requests, or through a discussion thread, to resolve other critical issues. At the end of the day, Dan is one rock solid community builder.

This already opens the door to using options unavailable before hand. The biggest one is how I want to extract fragments of source files into my manuscript. There is still a pending pull request to slightly alter the section format of the manuscripts, but this is structural and doesn’t interfere with my writing.

Cheers!