want better inline help for pushing a new branch

[Tiefflieger]

I'm a programmer myself and familiar with CVS. I was very curious about the possibilities bazaar (or in general, distributed VCS) could give me.
As mentioned in https://answers.edge.launchpad.net/launchpad-bazaar/+question/61004 , my first steps with bazaar were quite frustrating. There are tons of "mini-tutorial-faq-guide-get-done-in-5-minutes" pages for bazaar out there. But all I wanted to know, is how I can upload my local files (say "/myproject/myfile") to launchpad. "bzr push lp...", as proposed by launchpad, didn't work.
The problem was, I didn't know how to tell my local bazaar to create a local branch.
So please don't make another long long help-page on how to upload files (there probably already is one). Just a fiew lines shown in Detail-view for an empty branch would do just fine. Maybe something like
"To create a local branch called 'peterpaul' in current working directory: bzr branch peterpaul"
"To add all local files to the branch: bzr add"
"To locally save latter: bzr commit"
"To upload the local branch to branch 'peterpan' of project 'yourproject' on launchpad: bzr push lp:yourproject/peterpan"
I don't know if these lines are actually correct, and I'm aware that this is just one of many different ways on how to upload things. But it seems to me, that this would be the main case for most people, and for the others it gives a feeling for how bazaar works. And for further informations, one could contact the launchpad's help, but for these simple things, I don't want to crawl thousands of pages to find out how to do them.

--
Thanks for Launchpad :-)
Tiefflieger

[Karl Fogel (kfogel)]

Tiefflieger,

Thank you for the feedback. Yes, it can be hard for new users to figure out how to use Bazaar in Launchpad, especially if they're new to both tools. While I tentatively agree that something like the help hints you propose might be a good solution, especially on an otherwise empty branch page with no other information, I have to emphasize the "tentatively": providing context-sensitive help is a fine art, and the UI / documentation may already have other plans to address this.

The question you ask in https://answers.edge.launchpad.net/launchpad-bazaar/+question/61004 is a good one: why didn't the empty branch show up in Launchpad from the start? Why did it wait until there was one file in it? That might need to be a separate bug report.

[Tiefflieger (tiefflieger)]

Hi Karl Fogel,

So should I suggest the idea somewhere else, a place related to UI/documentation? Or is the idea automatically proposed to people it concerns, and I can be sure it's been taken care of (i.e. someone eventually decides if its good or bad)

To your second point: I think there was a misunderstanding, the empty branch did show up in Launchpad, but the userhint "Get this branch: bzr branch lp:cassiopeia/0.001" didn't :-) . Latter would have been very usefull, since I would have at least known howto locally initialize bazaar

[Karl Fogel (kfogel)]

Oh, I misunderstood, then.

I kind of agree with Curtis (in the Answer). For example, assume that the user is using command-line bzr: what if they're using Eclipse or some other GUI or IDE? We kind of have to assume that the user knows the basics about Bazaar, or knows where to find them.

Of course, we should make Launchpad as intuitive as possible! But we also have to consider lots of use cases, and we have to avoid UI clutter... it's a challenge.

Don't be offended if the UI team closes this bug report as "invalid". It doesn't mean they're not working on improving the Bazaar/Launchpad integration UI, it just means they already have enough information about the problem.

[Karl Fogel (kfogel)]

I meant to say "For example, we can't assume that the user..."

(Dunno why I keep dropping words the last few days. Is it some my brain?)

[Tiefflieger (tiefflieger)]

Don't worry, I won't be offended - I somewhat know the struggle making an application as intuitive as possible.

So my arguments were that these hints would not only be helpfull to command-line users, but also to others, as it gives hints on how bazaar works.

Again, I won't be offended - Bad feedback is better than no feedback ;-)

[Martin Pool (mbp)]

Tiefflieger is raising some good questions here and we'd all support making Launchpad and Bazaar more intuitive, but this is not really an actionable bug at the moment. What exactly is wanted? A short guide specifically about using Bazaar with Launchpad?

[Tiefflieger (tiefflieger)]

Please, not another short guide :-)

I attached some kind of log in which I wanted to point out my problems when first using Launchpad's bazaar.
(btw, In a newly registered branch, shouldn't be the hint "Update this branch: bzr push lp:~tiefflieger/cassiopeia/test" rather be "Update this branch: bzr push lp:~tiefflieger/cassiopeia/test --use-existing-dir", as the first won't work, even if you have a working local branch?)

I'd suggest some short hints for the use case thats as simple as can be in my eyes: Putting a directory and its content under version control in Launchpad.
These hints would appear in empty, newly registered branches only:
"To put a local directory under launchpad's version control with the console, execute following commands in that directory:
bzr init #initializes local bazaar branch
bzr add
bzr commit #add all contents to that local branch
bzr push lp:mybranchlocation --use-existing-dir # upload local branch to launchpad's branch"
That would be an extension of the existing user hint: "Update this branch: bzr push lp:~tiefflieger/cassiopeia/test", but with some kind of context-sensitivity.
But I understand Karl Fogel's point, too - it's just a suggestion, I can't decide whether or not it's really that good like I suppose it to be ;-)

[Martin Pool (mbp)]

So you're saying the bug is: on a new empty branch created on
Launchpad, we should display a small set of sample commands for how to
push to it?

That makes sense.

There is some broader context though: a thing called 'guided project
registration' by which we take people through the whole process of
starting to store their source on Launchpad, and also I believe
~thumper wants to remove or reduce the prominence of creating branches
through the web ui. Instead people will just push to create them.

[Jonathan Lange (jml)]

Martin, Tieffliegger,

Currently new empty branches have:

Update this branch:
bzr push lp:~jml/testtools/testing

In big letters just below the branch name. What else do we need?

jml

[Tiefflieger (tiefflieger)]

Hi Jonathan,

this is exactly my issue was about.
Acting naive, the command
bzr push lp:~jml/testtools/testing
just won't work if you haven't put your local directory under version control yet, which is the case if you want to get to know bzr for the first time.

Martin stated my concern quite well:
> So you're saying the bug is: on a new empty branch created on Launchpad, we should display a small set of sample commands for how to push to it?

Say I have no idea about bazaar. I have a local non-versioned directory which I want to upload to a branch on launchpad. The hint you mentioned does not work. A few sample commands on how to do this would be really helpfull.

More info about my misunderstanding: http://launchpadlibrarian.net/24010162/lpsbazaar

[Martin Pool (mbp)]

I think listing all the commands you could use would just make things confusing, but maybe as well as 'bzr push' it could link to a help page.

[Jonathan Lange (jml)]

I agree with Martin.

[Tiefflieger (tiefflieger)]

I was not thinking about listing ALL possible commands, just one sample to get started in the most common scenario:
Putting a local directory (via console, which is to me the fallback if everything else fails) under version controll and bind it to launchpads VC.
Like I said, there are plenty of "Short-tutorials-get-done-in-5-minutes-quick-introductions" out there, so please keep this new page as short as possible.

[Jonathan Lange (jml)]

The main problem I'd have with including the sequence of commands that you list above is that there are quite a few ('init', 'add', 'commit' and 'push') and they need extra text to explain in which context they are relevant.

As someone who has been using Bazaar for ages, my ability to assess this sort of thing has been dulled. I cannot see what properties make the current in-page documentation "not enough" and the many external short tutorials "too much". Could you please explain this?

I agree that it is really important that we make this dead simple for new users. That's why I'm keen to understand your thinking.