Opened 2 years ago

Last modified 23 months ago

#3635 new enhancement

Improved Buildstep Docs

Reported by: wangofett Owned by:
Priority: minor Milestone: 0.9.+
Version: 0.9.0 Keywords: docs


Right now in the Build Step docs (particularly for git) it says:

(optional): this specifies the name of the branch to use when a Build does not provide one of its own. If this this parameter is not specified, and the Build does not provide a branch, the default branch of the remote repository will be used.

Apparently, though, when used with a GitPoller it doesn't use the *default* branch, it uses whatever branch triggered the change. This is not at all clear from the documentation.

Change History (9)

comment:1 Changed 2 years ago by sa2ajj

I'm not sure I understand "not at all clear" here: the documentation you quoted says "the branch to use when a Build does not provide one of its own." When GitPoller creates a change, it does indeed provide a branch to use.

How would you like it to be re-phrased so it's clearer from your point of view?

comment:2 Changed 2 years ago by wangofett

Reading just the documentation, how would you know that a GitPoller provides a branch? How would you know that there is anything besides the build itself that provides a branch? It's not mentioned in the tutorial - and I don't even think that the GitPoller documents that it provides a branch name to the build that will be used in the build.

Last edited 2 years ago by sa2ajj (previous) (diff)

comment:3 Changed 2 years ago by sa2ajj

By just reading the tutorial, no, one can't really get this idea. However I would expect to get this understanding while reading Concepts chapter.

There's one bit in the documentation which is very well overdue: guides. These would probably allow to better deliver concepts and specifics to the new (and not so new) users.

Good documentation is hard, that's why I asked how would you like to see it changed so it'd be of better help.

comment:4 Changed 2 years ago by sa2ajj

  • Milestone changed from undecided to 0.9.+

comment:5 Changed 2 years ago 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 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 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 :)

Last edited 2 years ago by sa2ajj (previous) (diff)

comment:6 Changed 2 years ago by sa2ajj

I really appreciate what you have suggested: it supports very well that a git[hub] guide would be very helpful indeed.

comment:7 Changed 2 years ago by sa2ajj

I would like to complete the migration of tickets from trac to GitHub (please note I set the milestone so this ticket is migrated) and then have a look at what I have (I started a Git work flow related guide quite some time ago, but never had time to finish it) together with what you have written here.

And yes, we know that some parts of the learning curve are steep, it's just very difficult to see things from a point of view of a new comer when you have all this experience you have :)

comment:8 Changed 2 years ago by wangofett

Migration of tickets to Github will be quite appreciated :)

Note: See TracTickets for help on using tickets.