Eric's Thoughts

Prepping for the Pacific Crest Trail

Thu, 04 Apr 2013 19:00:00 -0000

Prepping for the Pacific Crest Trail

My time in Portland in winding down, and the trail is approaching in my minds eye. I leave on the 14th of April, and 6 in the morning. Setting out on a jet-plane to San Diego. I will spend the night on the 14th and be transported to the trailhead at sunrise the following day.

Prep

I have been attempting to walk 10 miles a day, and gain 1000 feet of elevation. I have been using a Fitbit to keep objective data about my day, and I’ve been doing pretty well in this department. My longest hike was a 20 mile hike that went from Terwilliger Blvd in Southwest Portland, along the west hills, into Forest Park. That day exhausted me, but it was good to see my body could do 20 miles in a day, seeing that’s what I need to average to complete my journey.

Gear

I have my gear pretty much dialed in. My gear list is available on Postholer, and is mostly up to date. I’m pretty happy with all of my gear selections, having done a couple of test hikes overnight.

Online Presence

I have been gathering my online assets together, and consolidating. I have moved my blog from a Django app into a Sphinx repo hosted on Read the Docs. That will make it much easier to update, and I don’t have to worry about database backups or anything. It’s all based out of a git repo, and hosted on Read the Docs, which is highly available.

This means I only have 1 personal server left, and that is running my IRC bouncer. I will likely keep this around just for fun, but I will likely knock down the buffer size on my bouncer so that it doesn’t overwhelm my phone when I log on in the woods. I’ll want to be able to chat with people and keep logs of the channels I’m in, but I don’t need all the scrollback after a week of walking.

Mental Prep

The big part of the journey currently is just getting my head into a good state. The concept of hiking the PCT is becoming very real, and it’s scary and exciting as hell. I know it will be an amazing experience, but it’s quite the physical feat. It’s also something different; something I have never done anything like before. It’s that nervous feeling that you get when you are pushing your limits.

I am trying to step back from the emotions I’m experiencing to appreciate the experience of it. Much like watching a movie, I need to appreciate the fear and apprehension that I’m experiencing as an artifact of doing something important and necessary. There is common wisdom that goes along the lines of “The things that scare you the most are the most important to do,” and I’m trying to keep that mindset in the front of my mind.

Announcing Write the Docs

Mon, 28 Jan 2013 09:05:26 -0000

Announcing Write the Docs

Documentation is one of the most important parts of a software project. However, a lot of projects have little or no documentation to help their (potential) users use the software. A few years ago we started Read the Docs to help make hosting documentation easier. Part of the reason was that if hosting documentation was a solved problem, it would make people more likely to write docs.

However, there is still a large hole in the documentation world around writing documentation. There are some resources about it, but they are scattered around the internet in random places. Write the Docs is trying to solve this problem by getting all of the people that care about documentation in a room, to improve the art and science of documentation.

Write the Docs is two things. The first and more immediately interesting is that it is a two day conference in Portland, Oregon. Held on April 8-9, it will bring the community that exists around documentation together. Through this event we will spread a lot of knowledge about how, why, and when to write documentation.

The second part of the project is a resource for people who are writing documentation. It will solve the problems of someone who has the question: I want to write docs, but what do I write?!. It will be a home of best practices around documentation, and a lot more. We hope it will serve as a growing resource of all things documentation. We want to build the canonical source for people who have questions about documentation, and to further the art of documentation in all forms.

Write the Docs will also be a community that you can become involed in. We are announcing a mailing list that will serve as a place to ask questions, and bring together all those who write the docs. In addition, the Write the Docs Sphinx repository is open source, and accepting contributions to the information there.

All of the above is a work in progress. I hope you join me in supporting and contributing these projects. I believe that they will advance the state of the software community in many ways. The vision for the project lays out some of the things that we want to accomplish.

Remember: Docs or it didn’t happen :)

A Walk in the Woods

Thu, 10 Jan 2013 19:08:43 -0000

A Walk in the Woods

I’ve recently schemed some very large changes in my life, and I have been trying to figure out how to blog about it. It all starts with quitting my job at Urban Airship. I sent an email to the staff announcing my departure, and I can’t think of a better way to remember this moment in time than to include it in full in my blog. So, here is the letter I wrote to everyone at work when I left the company.

All,

It’s with great anticipation and mixed feelings that I announce the end of my ride upon the Airship.

For I am leaving to face a greater challenge and a personal life goal. I will be attempting to walk 2650 miles from Mexico to Canada along the Pacific Crest Trail starting in the spring. Doing a thru-hike of the AT or the PCT has long been something I have wanted to do, and I am in a place in my life where the responsibilities I have are minimal, so it seems like a great time to go walk in the woods for 5 months. The approximate timeline is from April 15~September 30.

Pacific Crest Trail

I will be starting training for the hike immediately, and that is hard with a full time job. Luckily, I have been offered a contract gig to work on my side project Read the Docs for as many hours as I want until I leave. This is another life dream come true, the ability to get paid to work on an Open Source project that I have created.

With this confluence of fortune, I leave the Airship for what should be one of the most amazing years of my life.

I would like to thank everyone who I have had the opportunity to work with here at UA, because it has been the best job of my life. Watching the company grow from 15 to over 100 people has been a formative experience in my professional life. I can only hope that I will get another chance to watch such an amazing group of people build such a great company again.

My last day will be Friday, Jan 18th. So, feel free to come accost me while I’m still here and ask me questions, or call me crazy, or give me hugs. I’ll also be kicking around in Portland until April, so I should still be around for the PDX Python meetups and other bits and pieces.

My personal email address is eric@ericholscher.com if you want to keep in touch. I will be blogging about my experience on my website at http://ericholscher.com, if you want to follow along. There isn’t anything there yet because this wasn’t public knowledge, but I will start posting about it soon.

Cop High Five

“Live in each season as it passes; breathe the air, drink the drink, taste the fruit, and resign yourself to the influence of the earth.” ― Henry David Thoreau, Walden

Cheers, Eric

tl;dr:

I’m leaving Urban Airship.
I’m going to be hiking 2650 miles from Mexico to Canada on the Pacfic Crest Trail starting on April 15, hopefully ending near the end of September.
I’ve gotten a contracting gig to work on Read the Docs (my open source side project) for as many hours as I wish until then.
How much I love you: lots

tl;dr gif:

Oregon Trail

2012 Year in Review

Mon, 31 Dec 2012 08:06:17 -0000

2012 Year in Review

Wow, what a year. 2012 was a great year in my book. I took 2012 off from a lot of the professional development activies that have taken up my adult life thus far, and really focused on personal development. I think I did a great job with that, and I have a pretty awesome list of things I accomplished this year. I think I also started to get the full enjoyment out of Oregon this year, in all its seasons.

Physical achievements

The biggest achievement of the year has to be the Petal Pedal I did in June. That’s a 100 mile bike ride through the Willamette Valley in Oregon. I trained for it through most of the spring with rides that started out around 20 miles and ended up in around 70-80 miles. Previously the longest bike ride I had done was probably around 10 miles. The official ride also had 5000 ft of eleveation gain, which added another element of difficultly. The ride was beautiful though, and went through a bunch of flower fields and Silver Falls State Park.

Earlier in 2012, I also started taking up skiing again. I went up to Ski Bowl for night skiing a bunch. I went ahead and bought a season pass for Ski Bowl for the 2013 season.

As summer came to Portland, I was outside pretty much all the time. It was a most excellent summer weather-wise and I took full advantage of it. I did a bunch of backpacking up on Mount Hood, with a number of weekend trips to various places including Carin Basin and Paradise Park. I also went car camping a bunch, including at Rock Creek in the Santiam State Forest, and Trillium Lake on Hood. I also stayed in a Yurt on the Oregon Coast for the first time at Cape Lookout.

The summer also included a couple fun road trips. I got down to see Crater Lake, the only national park in Oregon. We camped there for a night and drove around the rim. It is one of the most amazing places I have ever been. It’s a crystal clear blue lake, but it’s in the rim of an extinct volcanoe, at around 5000 ft elevation. It’s a really amazing geological place and highly recommended. After that, we drove up to Bend, and camped at Lava Lake, which is also a beautiful place. We saw tons of ground squirrels and other wildlife there. We also went through Bend and walked around, and checked out Smith Rock. The trip concluded with a sunset walk up to Mirror Lake on hood, and a race against the sun to get back to the car.

I made it back home for 2 of my good college friends getting married (to each other) in DC and visited family in Virginia. I got some surfing in down in Virginia Beach, which was great. It’s something I miss about Oregon, because the water is so cold here. Made it out to the Oregon Coast, but it’s mainly just good for looking instead of swimming in.

The summer also included some awesome hikes and other activities. I went out to Hood River a couple times, and actually Wind Surfed and Paddle Boarded for the first time. We also drove around the east side of Hood to the Fruit Loop and gorged on cherries and other delicious fruit. Speaking of fruit, I ate a ton of berries again this year, with Oregon having some of the finest summer farmers markets in all the land.

Hiking was a big draw this year. I went on a number of hikes including the PCT from Timberline Lodge all the way to Cairn Basin on a couple different days. Eagle Creek, Angel’s Rest, Dog Mountain, and a few more in the Columbia River Gorge. I hiked the Wildwood trail through Forest Park a number of times, however I didn’t thru-hike it’s 30 miles, will have to save that for next year.

As fall came around, things started to slow down. I still did a bunch of hiking through the fall, and riding my bike. I started rock climbing around this time to keep up the activity level, and have been progressing nicely at indoor climbing at the Portland Rock Gym. I can’t wait to test my skills outside, but I already noticed my balance and confidence improving on the hikes I did in the fall.

As winter came into view, I escaped down to the Turks & Caicos islands for Christmas. Where I did 7 dives, got my Advanced Open Water cert, and did a bunch more snorkeling. It was great hanging out with my family in the warmth, and spending time in the water. When I got back, I went on my first snowshoeing adventure ever on Hood. I really like snowshoeing, it’s basically just like hiking in the snow, just it takes a lot more work!

This year was also full of Ping Pong. We have a table at work, and it’s rekindled my love of the game. I played some when I was a kid, but we have gotten pretty good and serious at work, and it’s been a pleasure upping my skills again.

In list form

A list of firsts for the year:

Rock Climbing
Backpacking
Wind Surfing
Paddle Boarding
Snow Shoeing
Long Distance Biking

Things that I love that I did more of this year:

Ping Pong
Hiking
Camping
Skiing
Diving
Snorkeling
Biking

Things I love that I didn’t do so much of:

Surfing
Traveling
Soccer
Frisbee

New things I want to try next year:

Bike Camping
Longer backpacking trips
Climbing outside
Climbing Mount Hood and/or St Helens
Thru hiking Forest Park
White Water Rafting
Kayaking

Conclusion

I’m sure I missed some stuff, but it was a year full of firsts, and I think I have gotten the most out of Oregon that I could. I chose to focus on my personal life this year instead of my professional life, and I think it’s worked out for the best. I have had an amazing year full of excellent activies outdoors.

I also saw a bunch of music this year, and met a bunch of awesome new people, and did a bunch of great things professionally, but I think the points worth remembering will be the parts above.

As a wise man once said: Work to Live, Don’t Live to work.

Interesting projects on Read the Docs: Teaching

Sat, 01 Dec 2012 18:27:15 -0000

Interesting projects on Read the Docs: Teaching

As the maintainer of Read the Docs, I spend a lot of time looking through random projects, and getting inspired. People have been doing lots of interesting things with the project, and I’d like to highlight some of them.

This edition is focused on teaching. All of these projects are trying to teach something, and doing it in different ways. Some are community contributed guides that have many authors, where some are a single person trying to distill their experience into something valuable for others.

The projects mentioned here will be featured on the homepage of Read the Docs until I do another posting, where those new projects will take their place.

Little books of R

The Little Books of R were some of the first books that I was aware of on Read the Docs. They are great little manuals on things that you can do with the R programming language, often used for modeling and graphics.

There are a few different books, including how to use R with:

These books are perfect examples of what publishing online provides. Short and sweet, to a specific niche, and easily available.

Ops School

Ops School is an attempt at providing a cirriculum for someone interested in learning Systems Administration. It’s answering the question of “What do I need to know to get a junior sysadmin job” that many people have before starting into a career.

It takes a lot of knowledge that takes years to gather from experience and attempts to distill it down into a form that is easily referencable. As this project matures, it will provide a valuable resource for a lot of information around the running of systems.

The project is still in development, and is actively seeking contributors.

The Hitchhiker’s Guide to Python

The Hitchhiker’s Guide is a great project from the Python community. It’s goal is to provide knowledge on best practices on the daily usage of the Python language. It is trying to answer the question “What do I need to know that I don’t know I need to know.” Known more colloquially as unknown unknown’s, this knowledge is the hardest to gain. Having a guide from the community about the things that you should probably know about is invaluable as a new, or even experienced member of that community.

This project is also in active development.

Thoughts on RESTful API Design

These thoughts are a great collection of experience from someone who has built production REST APIs. If you are tasked with creating an API for a web site, it’s a great read. It provides a good framework for understanding how the API fits in with the rest of the application, as well as what makes a good API.

Conclusion

I love the idea of Read the Docs as a medium of teaching, as well as just documenting software projects. Please let me know of other interesting projects that you’ve found, and I can include them. Raising awareness of these great resources is valuable, and hopefully it will reach more people who can learn from them.

Help fund Read the Docs

Thu, 20 Sep 2012 12:04:59 -0000

Help fund Read the Docs

Currently Read the Docs is funded mainly through Corporate sponsorship. The Django and Python Software Foundations (non-profits), Mozilla, Lab305, Revsys, and others have helped keep the site running. However, this requires finding sponsors to help donate to the site every 6 months or so to keep things running.

I want to try out a new idea that is effectively a subscription to the website. When people pay for something, they expect certain things. A promise of support, uptime, and other work are basically being transfered in the mind of the person providing payment. I know some places try to explicitly denounce this transaction, but it is still there.

This is where Gittip comes in. It has the idea of funding a person to do work through anonymous donations. The thinking behind this is that the person recieving the money now has no sense of obligation to the person giving money. This allows them to take the money and continue to work on Open Source without feeling pressured to work on the things a specific person giving them money cares about.

I think this same idea can apply to software projects. Read the Docs doesn’t cost a huge amount of money to run every month - it costs a lot less than keeping a person alive and happy. So, I think that the first success story for Gittip funding something could easily be a project instead of a person. This funding model would then allow Read the Docs to support itself over time - without having to try and get support and investment again.

Read the Docs currently costs about $300/mo to run. This includes 6 servers (2 web, LB, Build, Database, Util/Monitoring), over 350GB of data transfered, over 100GB of repositories, and it serves over 3 million page views every month. We expect these costs to slowly rise as we get more and more traffic, but that is the goal we are currently aiming to hit. Head to the Read the Docs gittip page if you want to help out.

This is the beauty of Gittip - when 75 different people are giving you $4 a month ($1 a week), one can stop giving and it doesn’t totally destroy the funding. It allows other people to pick up the slack, and to sustain a dependable revenue stream for the project.

This is an experiment that I am going to try running to see if we can get individual sponsorship for the project, instead of depending on corporate sponsors for the sole source of support. Once this is achieved, we will look at other ways to spend the sponsorship we get from corporations, perhaps in more traditional efforts to advance the code base.

If this sounds interesting to you, head over to the Read the Docs gittip page, and start donating to the project.

Update: Wow! We reached the goal of $75 in around 14 hours. Thanks everyone who has donated to help keep the site running! It looks like we might reach above our weekly goal. For now, that money will just be left in an account to help pay for future growth of the site. If we end up making way more than we need, we’ll find something awesome to do with it (CDN?!).

The festival that felt like a hug

Tue, 18 Sep 2012 13:29:38 -0000

The festival that felt like a hug

A story about XOXO Festival in 3 acts. I will start first with something that set the tone, then talk about the importance to me, and then what I hope comes from it in the future.

Act 1: Interjecting awesome

One moment stood out to me in the swirl of ideas and amazing that was XOXO. It was at the beginning of the conference, when the organizers were on stage. They were talking about how they wanted the conference to be experienced. The sentence that I think changed the entire conference experience for me (paraphrased):

This should be a conference where you can go up to a group of people you don’t know, and they will include you in their conversation.

This seems like something very simple, but it set an important social contract. Normally my introverted self will balk at the idea of joining a group of unknown people. Especially at a conference with so many people who I look up to and admire. However, this idea, set forth by the organizers, dispelled this apprehension, and instead I viewed it as my responsibility to interject.

This was a fundamental change in how I experienced the conference. I spend most of my time at conferences talking to people I’ve known for years, rarely breaking into new groups. At XOXO, though, since I knew only a few people beforehand and felt compelled to meet new folks, I spent the entire conference striking up conversations with complete strangers. This was a profoundly different and amazing experience.

Act 2: Bring out your trolls

Consuming the world through twitter is not a way to be inspired. Getting together in a room and seeing people who have changed their world, and the world for others, is an amazing experience. It allows you to perceive and appreciate people’s aspirations.

I started XOXO in a funk that can only be explained as cynical. I had heard of Kickstarter and the ilk, but never really invested or taken the time to fully let the idea wash over me. As the talks started, and I heard Kickstarter over and over, it at first felt like a promotion and a buzz word. However, through the genuine excitement and joy of bringing something new into the world, my skepticism turned into inspiration.

Greed being destructive was a theme behind the conference, and I think this is the primary thing that won me over. People were creating things because they wanted them to exist in the world, and they had to do it. It wasn’t about making money, or getting famous, but because they had a drive to change a part of life. This drove the jealousy and skepticism from my heart, and started the search for the thing in life that I was meant to change.

Act 3: Radiating change

I think that this conference was an amazing view into a world that could exist. At a high level it was a distancing from the classical tech world that is so focused on money. A place where we can be open, share our ideas, successes, and failures. Somewhere that people can actually introduce something into the world and have support for it.

During the talk on Kickstarter, Yancey mentioned that Portland has been the most successful city on Kickstarter. Something like $7.5M has been given to creators in the rose city. On the technical side, we have a burgeoning, but not well formed start up community. This means that we can form this community into something that is different than has existed in other places.

As Paul Graham once said, each city sends you a message. I think that this conference was in some ways a call to action, that a place like XOXO needs to exist in a more permanent manner. I think that Portland has a chance of doing this going forward. I can’t, and won’t, try to spell out how this could be done. I will say that I can’t imagine another city that is better poised to do it.

I want Portland to be the place where you come, and think you can change the world.

Why Read the Docs matters

Sun, 22 Jan 2012 14:08:01 -0000

Why Read the Docs matters

Documenting projects is hard, hosting them shouldn’t be. Read the Docs was created to make hosting documentation simple. I think that we have solved this problem well, but now we need to start thinking about the larger picture.

Along with hosting, Read the Docs was created with 2 other main goals. One was to encourage people to write documentation, by removing the barrier of entry of hosting. The other was to create a central platform for people to find documentation. Having a shared platform for all documentation allows for innovation at the platform level, allowing work to be done once and benefit everyone. Having run the site for over a year now, I think there is a third thing that we should be striving for. That is to make the quality of documentation better.

I think that we can help a documentation culture flourish within the open source world. Django is a shining example of what a project with great documentation can do, and it has a community that values docs more than the norm. I think we can help spread this culture throughout the Python world, and beyond. This has already started, and I want to think about how something like RTD can help.

What we can do to help

I think that having a guide for writing useful documentation would be a great step towards helping people along the path of documentation enlightenment. Jacob Kaplan-Moss has started down this road with his blog series and Pycon 2011 talk on this subject. I think that we could start by collecting these into a section of the site.

We could build on top of that great start with simple guides for how to get started with Sphinx, best practices for documentation, and providing a general place to learn more about how to write good documentation. Since we host a lot of documentation, we could point to live examples of techniques, and provide helpers for people to enable the techniques.

I have started a reStructedText Philosophy document that is meant to help people understand the ideas behind how reST works, so that it isn’t as mystifying. This reST cheatsteet also appears to have similar goals. These are a very basic start, and I think some more along these lines would really help a lot of people get over the barrier to starting and continuing to write good documentation.

I think that we could also help create contributors to projects, if we could find an easy way to provide patches to documentation. If you could go to the project documentation, and fix small typos, or help add a paragraph in the tutorial, it would lower the bar to helping.

However, it isn’t a wiki. These changes would be represented to the project author as pull requests in their VCS, and they would still be responsible for tending the garden. This gets rid of the “Just Edit The Wiki” solution of documentation, and also helps new contributors get started in an easier fashion.

The Plone community has built a proof of concept, linking to Github’s edit pages for the current document. I think we can integrate this at the platform level, and make it available to everyone.

Want to help?

Read the Docs is open source. You can help by writing docs for the site, writing code for the site, or just writing documentation in general. People can also help just by using the site, and reporting bugs. Telling us how to make the site better helps everyone in the long run. Come join us on Freenode in the #readthedocs channel as well.

Another area that we’re hurting is in the design front. We have been adding features over time, and the design of the site is getting a bit strained. Having someone with a good sense of design help re-think and re-architect some of the features and ideas that we’ve been working on I think would help a lot.

A lot of the RTD contributors will be at Pycon 2012, where we will be having a sprint on the site. If you want to get started contributing, that is a great place to come and get started.

Read the Docs Update

Mon, 11 Apr 2011 19:22:37 -0000

Read the Docs Update

It’s been a while since I last talked about Read the Docs, and there has been a lot of activity. This is an update on the latest and greatest new features.

PSF Funding

The biggest news that has happened is that we have been given a grant from the Python Software Foundation to help host the site. Thanks PSF! They have blogged about it, and I am grateful that they have given us support. With the funds they have offered, we have been able to make Read the Docs a lot faster, and more robust. I will outline some of the changes below.

This also means we won’t be going away any time soon!

New Theme

We have a fancy new theme for documentation on Read the Docs! If you have the ‘default’ theme for your project, it will show up on the build of your docs on the site. I think it is pretty great, thanks to the designers who spent their time making it awesome. A really great feature is that the new theme is mobile ready. Go ahead and view a project using it on your phone, or make your browser smaller and you will see the fanciness. Having a custom theme will give us a base to build lots of other neat features on top of.

Better architecture

We had some connectivity trouble in between our servers a while back, and this prompted me to make the site respond better to these conditions. Every time you view documentation on a subdomain of readthedocs.org, your request will never hit Django. So all of these requests will work without a database. We have also added a second application server with a load balance in front, which means that one of the app servers could go away and your documentation would still get served.

That leaves our load balancer as the main single point of failure at the moment. We’re using Varnish for the load balancer, and we’ve implemented strong caching of data. Varnish will cache your docs for up to a week, and it will be actively purged when you rebuild your docs. This means that your docs will usually be served out of memory, and without dependence on any other server but that one. We have plans to elininate Varnish as a single POF, and then it would only be our hosting provider that would be a single point of failure (famous last words).

Intersphinx support

Intersphinx is an awesome feature of Sphinx that allows you to reference remote sphinx documentation easily. RTD now supports it for every project that we host.

Improved rtfd.org

I’ve always had big ideas for rtfd.org, since it can act as a short-url for things. projectname.rtfd.org has always redirects to the projects docs, but now we have something a lot better. Inspired by Jacob Kaplan-Moss and his work on django.me, we now support human-edited deep-linking within documentation hosted on RTD.

Taking another page from Jacob’s book, we seeded the index of our projects with their Intersphinx data, so a lot of references will automatically work. This works best with API reference docs, but anything people have put links to in their documentation should have been picked up. A couple of examples:

If you go to a non-existent link on rtfd.org, you will be prompted to enter a suggested URL. This will help build the data, and make it more useful for everyone.

rtd command line utility

RTD has had an API for a while now, and with the addition of the support for rtfd.org, I thought it would be neat to make it easier to access docs from the command line. With a simple pip install rtd, you will get an rtd utility that will open docs on RTD. It supports 2 arguments, the first being a project name, and the second being a slug to append for the rtfd.org functionality. So like the example above:

-> rtd pip
Pip Installs Packages.
Opening browser to http://pip.rtfd.org/
-> rtd celery Task
Distributed task queue
Opening browser to http://celery.rtfd.org/Task

It hits the RTD API to see if the project is on the site, and only opens your browser if it doesn’t exist. I hope that in the future we’ll make it easy to upload a project from the shell, and more.

More docs

Since we are a documentation site, we’ve always had documentation. I’ve been adding more as time has gone on, and most of the features I’ll be talking about today are already documented. I also broke the documentation up into sections for users of the site, and developers on the codebase, so it should be easier to find for everyone to find what they are looking for.

Conclusion

I think that RTD can be doing a lot more to help out the community with regards to documentation. I’ll write another post about that soon. But if you are interested in helping out with the effort, all of the code is open source and we love people to contribute. Feel free to jump in #readthedocs on Freenode as well, if you have any questions or thoughts.

Using Reviewboard with Git

Sun, 23 Jan 2011 21:25:40 -0000

Using Reviewboard with Git

Reviewboard is a great tool for managing the process of Code Reviews. It has pretty good git support, but it might not be obvious what the best way is to use it. At work, I have a couple of different ways of pushing up code for reviews, which I’ll talk about.

This guide is assuming you are using your own bare repositories, on the server hosting the Reviewboard instance. It’s mainly here so that I can remember how to do this next time I need to. Also, thanks to Travis Cline for the initial pointers for this post.

Setting up Reviewboard

Once you have Reviewboard installed, you need to add a Repository in the admin, which is located at /admin/db/scmtools/repository/. The required fields have the following values:

Name: The name of the project
Hosting service: Custom
Repository type: Git
Path: The path to the local checkout of the git repository (ex. /var/lib/git/name)
Mirror Path: The Url to the repository (ex. ssh://git@your.server.com/var/lib/git/name)

The Repository Documentation has more about why you need this screwy configuration.

post Review

Before we get started, you’re going to want to get the post-review tool that works along with Reviewboard. The easiest way to get it is to pip install RBTools.

Pointing to the right Reviewboard Instance

The easiest way to make sure your pointing at the right Reviewboard instance is the .reviewboardrc file in your home directory. You only need to add one line to that file, which is:

REVIEWBOARD_URL = "https://path.to.your.instance"

If you are working with multiple instances that map to different repos, you can set the Reviewboard instance for the specific repo as well:

git config reviewboard.url https://path.to.your.instance

Reviewing a Branch

Alright, now you are all setup to start posting reviews. The easiest way to do that is to branch off of master, and start committing. If you are following something similar to this awesome branching model, this should be your normal workflow. Once your branch is ready to be merged back into your project, you want to get it reviewed. You can send a review equivalent to “this branch diffed against master” like so:

post-review --guess-summary --guess-description

Reviewing one commit

Another thing I find myself doing a lot is working on my master, and only having one commit to review. In theory this should probably be done on a bugfix branch, but such is life. There are other good use cases for only reviewing the latest commit as well. It’s done like so:

post-review --guess-summary --guess-description --parent=HEAD^

Reviewing arbitrary number of commits

It’s also possible to review any number of previous commits. It looks a lot like the previous command:

post-review -o --guess-summary --guess-description --parent=HEAD~4 #To review last 4 commits.

If you are familiar with git, you will understand that there is a lot more that you can do with the –parent argument. I’ll leave the possibilities up to your imagination.

Eric's Thoughts

Prepping for the Pacific Crest Trail

Prepping for the Pacific Crest Trail

Prep

Gear

Online Presence

Mental Prep

Announcing Write the Docs

Announcing Write the Docs

A Walk in the Woods

A Walk in the Woods

2012 Year in Review

2012 Year in Review

Physical achievements

In list form

Conclusion

Interesting projects on Read the Docs: Teaching

Interesting projects on Read the Docs: Teaching

Little books of R

Ops School

The Hitchhiker’s Guide to Python

Thoughts on RESTful API Design

Conclusion

Help fund Read the Docs

Help fund Read the Docs

The festival that felt like a hug

The festival that felt like a hug

Act 1: Interjecting awesome

Act 2: Bring out your trolls

Act 3: Radiating change

Why Read the Docs matters

Why Read the Docs matters

What we can do to help

Want to help?

Read the Docs Update

Read the Docs Update

PSF Funding

New Theme

Better architecture

Intersphinx support

Improved rtfd.org

rtd command line utility

More docs

Conclusion

Using Reviewboard with Git

Using Reviewboard with Git

Setting up Reviewboard

post Review

Pointing to the right Reviewboard Instance

Reviewing a Branch

Reviewing one commit

Reviewing arbitrary number of commits

Other useful post-review flags