[Buildbot] #3635: Improved Buildstep Docs

[Buildbot trac]

#3635: Improved Buildstep Docs
------------------------+--------------------
Reporter:  wangofett    |       Owner:
    Type:  enhancement  |      Status:  new
Priority:  minor        |   Milestone:  0.9.+
 Version:  0.9.0        |  Resolution:
Keywords:  docs         |
------------------------+--------------------

Comment (by wangofett):

 I actually did read that chapter, and it definitely wasn't clear. I'm
 guessing that this is what you were thinking of?

   When it comes time to actually perform a build, a scheduler prepares a
 source stamp set, as described above, based on its configuration. When the
 build begins, one or more source steps use the information in the source
 stamp set to actually check out the source code, using the normal VCS
 commands.

 I can only share my experience, but for me just coming to buildbot, that
 statement isn't very clear.

 Practically speaking, I think what would give newcomers the best bang for
 the buck is to extend the tutorial. Right now I'm getting the feeling that
 it's about 25% of what people generally would be interested in doing. I'd
 be interested to see the numbers, but based on GitHub's popularity I
 suspect that 90% of people who first come to buildbot want to have a build
 that looks something like this:

 - have an incoming webhook to trigger the build
 - build their source into whatever the package looks like for their
 platform, whether that's a wheel for Python, a gem for Ruby, or whatever
 Go or something else uses
 - push that package to a specific location

 I'm guessing that a majority of projects also would love to have pull
 request integration - either GitHub or Bitbucket - where a pull request is
 automatically checked out, built, and the pull request status is updated
 based on the pass/fail of the build.

 I think that the biggest bang for the buck would be to continue the
 existing tutorial. Right now it leaves off at either the tour or the 5
 minute tutorial, which means that you've just got whatever was setup in
 the example config that builds pyflakes, with a force scheduler. And, if
 you're like me you saw the SVN part of the tutorials and went, "Ehhh do
 not want." Then I went and looked through the documentation and found
 http://docs.buildbot.net/current/manual/cfg-buildsteps.html#git and saw
 the bit about branches and thought, "Well, I guess I better provide a
 branch! I don't want to build master - that's only for production changes
 and I'm not ready to put anything into production right now!"

 The tutorial that I'd like to see would do something like this:

 - Here is installing buildbot and setting up the localworker. It builds
 this simple sandbox project that's on github using this thing that we call
 a force build (i.e. it's a pretty manual process)
 - What, you need other workers? Here's how to make some non-localworkers.
 - Building manually is terrible. Let's automate this with a scheduled
 poller. 10 minutes is the default, and you'll get bored, let's set it to
 60 seconds - go grab a cup of coffee. Oh and BTW we have these change
 sources and schedulers and pollers and build factories and build steps and
 loggers and this is how they all work together.
 - Well, that's swell, but if everyone in the world is using a scheduled
 poller most of the time there aren't actually any changes so they're
 producing all sorts of traffic to GitHub for no real reason. Plus GitHub
 created these nifty webhooks. Fork the sandbox project and set up your
 fork to push to a webhook when things change.
 - What, you require pull requests for your project? Well, buildbot can
 handle that, too! Here's how!
 - Oh, you'd like to
 [https://developer.github.com/v3/repos/releases/#upload-a-release-asset
 upload your releases?], you'll have to sign up for the github api, but
 buildbot can do that, too and here's how.
 - What's that you say, these things are great and all but you have some
 sort of Fancy Pants Special Snowflake Process™ that you want to do? Here's
 how you would make your FancyPantsSpecialSnowflakeProcessStep custom
 buildstep - here's how logging works and you have to do these magic things
 or everything blocks so do the magic things.

 I add that last bit about the custom build step because I tried to use it
 but I didn't find the documentation very clear and I got really frustrated
 with it, to the point that I almost just gave up on buildbot altogether
 because I couldn't figure out how to do what I wanted to do based on the
 documentation. I figure that I'm more persistent than most people, so it
 makes me wonder - how many potential users have given up on buildbot
 because they couldn't find the information they want/need? Rather than
 give up myself, I decided to at least try and improve things a little bit.
 So hopefully my perspective as someone fresh to buildbothelps out with the
 documentation :)

--
Ticket URL: <http://trac.buildbot.net/ticket/3635#comment:5>
Buildbot <http://buildbot.net/>
Buildbot: build/test automation