Live Snippet guide blueprint
Embed code from Butbucket Server
"The best way to learn programming is to read code of others." I don't know if that's a quote or where I got it from but I always think of it since then, because I find it very powerful and true. And working for a software company that produces a lot of code I feel like there is a huge library lying around on our Git server where there is so much to learn from.
And people often ask me "Hey Georg, I have this or that problem, can you help me with that" and often I say "Oh yeah, we have done something similar in this or that project". And then I look through the code, find the right pieces and send URL's to Bitbucket in Hipchat and say "Look here, that will help you out."
But sending URLs sucks. It would be better to create a nice page, maybe a step-by-step guide, with all the relevant pieces of code. But not with copied code, because copied code get's old very quickly. And not with sample code because that has the same problem as copied code and it's not real code, it's often too simplified or too generic.
What it does
The Live Snippets macro embeds code from Bitbucket Server into a Conlfuence page. But the key is that if you selected, for example, a method or a piece of XML and then later update the code, the snippet will adapt those changes. And there is also a Confluence blueprint that helps creating stet-by-step guides with code from Bitbucket.
How I built it
atlas-create-confluence-plugin :) It uses the Atlassian Applinks API and a diff library to figure out where the code changed. The plugin was developed at our company Shipit Day event 2016.
Challenges I ran into
The big challenge, of course, was to ensure that snippets still display the correct code if it changes, for example if bugfixes and new features are implemented. Otherwise this macro would be useless, I thought. Line numbers would always move around and mess up the snippet because code doesn't stand still.
Accomplishments that I'm proud of
I was convinced that the change detection was somehow possible because a diff view also shows you what changed, so I thought the snippet could also know how to adjust the line numbers accordingly.
I was playing around with diff libraries and tried to figure out how diffs work (yay, code reading :)). And my boss came into the room and asked "How is your project going" and I was like "Not good. Figuring out how the self updating thingy could work kinda takes too long and maybe it won't make it in the first version" and he replied "Nah. You can do it", turned around and left. Umm ok that was a weird motivational speech I thought :) But it worked and kept me going. I probably was the last one going to bed that day but in the end I was like "Now way!! It works!!"
What I learned
Well if course I learned how to use the Applinks API and how diffs work internally but I also created my first blueprint and I was impressed how cool blueprints actually are. They guide a user on how to create and structure information instead of forcing him like a conventional form based web app would do and that's pretty neat I think.
What's next for Live Snippets for Confluence
There is a lot of room for improving on how the code from Bitbucket gets to the Confluence macro. Pasting the URL is just the first step. And there's also more information to get from source code, than just the plain lines. And there are other ways of displaying it. From the short time using it until now, already a lot of ideas came up :)