Which version of buildstream for new user?

[Cynical-Optimist]

See original issue on GitLab
In GitLab by [Gitlab user @devcurmudgeon] on Jul 30, 2018, 15:42

From perspective of new user

• google buildstream, get buildstream gnome wiki page no sign of which version to use.
• click on first link, get buildstream gitlab page no sign of which version to use. may clone repo, get master
• click on link to documentation, no sign of which version to use
• click on link to Install, no sign of which version to use
• click on installing from source (recommended) and get led to install master, with dependencies

So at no point does the project say 'start with latest "stable" tag'. And FWIW the "stable" odd/even tag concept may be well understood in GNOME, but not by new users in general.

[Cynical-Optimist]

In GitLab by [Gitlab user @palvarez89] on Jul 30, 2018, 16:22

In the documentation you can see a "1.3.0+85.g4a3def5c". I guess that version number is from latest master, could also be confusing.

[Cynical-Optimist]

In GitLab by [Gitlab user @LaurenceUrhegyi] on Jul 30, 2018, 17:48

It's not clear what you are expecting to see as a result of this request.

I think the tasks here are:

• Amend the Install section of the documentation, explain the different branches we have and explain the odd (unstable) / even (stable) approach we follow
• Amend the potentially confusing note in the docs about "1.3.0+85.g4a3def5c"

It's probably not necessary to have this info on the wiki and the gitlab landing page. Would others agree?

[Cynical-Optimist]

In GitLab by [Gitlab user @devcurmudgeon] on Jul 31, 2018, 08:14

In the documentation you can see a "1.3.0+85.g4a3def5c". I guess that version number is from latest master, could also be confusing.

It's not just confusing, it's meaningless afaict.

[Cynical-Optimist]

In GitLab by [Gitlab user @devcurmudgeon] on Jul 31, 2018, 08:24

It's not clear what you are expecting to see as a result of this request.

I want the spinup experience for new users to be as painless as possible. This requires that we actually care about the users, look at the project from the user perspective, and that we make the path to use as simple as possible. Obviously in our rush to implement interesting functionality this has not been the case.

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Jul 31, 2018, 10:54

It's not clear what you are expecting to see as a result of this request.

I think your assessment that we need a mention of this in the installation guide, for installing from git, is correct.

There will always be a path to install from git, although I expect this will no longer be "recommended" once we've got ourselves included in downstream distros. At that point the same install from git will be more helpful to inform distro package maintainers, but also helpful for those who want to build/install from source.

In the documentation you can see a "1.3.0+85.g4a3def5c". I guess that version number is from latest master, could also be confusing.

It's not just confusing, it's meaningless afaict.

It is quite meaningful, it expresses the very exact version of BuildStream sources which the docs were generated from; generally it would be good to have a splash page allowing the user to select which stable version (or bleeding edge master/dev version) of the docs they want to view. Even though we document the "since" version for each feature that is introduced, publishing previous versions of the docs also allows us to rigorously refactor the structure of our documentation while preserving linkability in permanence.

This currently blocks on an upstream gitlab issue, see BuildStream issue #178

I want the spinup experience for new users to be as painless as possible. This requires that we actually care about the users, look at the project from the user perspective, and that we make the path to use as simple as possible.

Agree 100%, but this probably needs to be supported by a project website as well, not only as a part of the install guide, and certainly not as a part of the README (i.e. we should not encode the currently recommended version into the git project itself).

Obviously in our rush to implement interesting functionality this has not been the case.

Please refrain from making such assumptions, things take time and we definitely care about the user ramp up experience. Now we are starting to add tutorials and beginner facing guides, but this cannot come before full reference documentation coverage, which is essential even for us to ensure there is a comprehension of every option available in the format and provided by our plugins. Step by step, we are going to the right place.

[Cynical-Optimist]

In GitLab by [Gitlab user @jennis] on Aug 3, 2018, 11:16

Just to be clear, one of the proposed actions for now is to change the Installing commands so that we instruct the user to clone the latest stable version:

git clone -b 1.0.1 https://gitlab.com/BuildStream/buildstream.git

Is this the correct latest stable version, or are we ok to encourage users to install bst-1.2...?

[Gitlab user @tristanvb]:

(i.e. we should not encode the currently recommended version into the git project itself).

This action seems to contradict your statement here, thoughts?

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 3, 2018, 11:27

[Gitlab user @jennis] I don't think specifying the exact tag in the BuildStream repo, where the documentation is generated from, is a sustainable solution.

It would mean that we have to update the install guide in master (where the docs are built and deployed from), for every release made from the release branch - this does not make logistical sense at all.

My thoughts are that, on our non-existent website when it materializes, on the download page, we should indicate always the latest release tag we want people to use, and this should be automated (we don't have to touch the website, it will update itself when it's updating mechanism sees a new release tag in the BuildStream repo).

For the install guide, we should have some text indicating that the user should infer the latest release tag, or find out what it is by observing the download page of the website (once that exists).

With that said, it can be that we absolutely need a stop-gap solution until a website materializes; in which case I have to concede that we need to pollute the history with this noise until we get a website. Or, there may be some way (similar to how we have the "badges" which show coverage and pipeline statistics ?) that we can communicate the latest release tag through another channel such that the user docs embed the actual version tag ?

[Cynical-Optimist]

In GitLab by [Gitlab user @LaurenceUrhegyi] on Aug 10, 2018, 16:19

The content proposal for releases outlines content units which will solve the pain points here. So instead of hacking around this for now, I suggest we wait until that is in place.

[Cynical-Optimist]

In GitLab by [Gitlab user @LaurenceUrhegyi] on Aug 14, 2018, 12:32

mentioned in merge request !657

[Cynical-Optimist]

In GitLab by [Gitlab user @LaurenceUrhegyi] on Aug 14, 2018, 12:33

After discussing with [Gitlab user @jjardon] yesterday re the urgency, I have now submitted https://gitlab.com/BuildStream/buildstream/merge_requests/657

[Cynical-Optimist]

In GitLab by [Gitlab user @devcurmudgeon] on Aug 14, 2018, 14:00

[Gitlab user @LaurenceUrhegyi] i'm sorry but no way does !657 close this issue imo.

A new user should get an obvious link to download, without lots of redirects to other pages. not an explanation of SemVer and text describing the projects branching model

[Cynical-Optimist]

In GitLab by [Gitlab user @jjardon] on Aug 14, 2018, 14:45

[Gitlab user @LaurenceUrhegyi] agreed, the explanation is ok, but the version to use should be clear and easily accessible from all the links [Gitlab user @devcurmudgeon] mentioned in the issue

[Cynical-Optimist]

In GitLab by [Gitlab user @jjardon] on Aug 14, 2018, 15:29

[Gitlab user @LaurenceUrhegyi] [Gitlab user @devcurmudgeon] I have updated https://wiki.gnome.org/Projects/BuildStream to point to the current release/development snapshot

For https://buildstream.gitlab.io/buildstream/, some options:

1. Add the same contents of the wiki in the main page (and then remove the info from the wiki and redirect there)
2. Add the same contents of the wiki in https://buildstream.gitlab.io/buildstream/main_install.html (and then remove the info from the wiki and redirect there)
3. Add a new "Releases" section in the left pane, so it would read: (and then remove the info from the wiki and redirect there)

- About
- Releases
- Using
- Reference
- Contributing

I think best is to go for 3, then we can automate the creation of that section at some point. Thoughts?

[Cynical-Optimist]

In GitLab by [Gitlab user @jjardon] on Aug 14, 2018, 16:05

mentioned in merge request !661

[Cynical-Optimist]

In GitLab by [Gitlab user @LaurenceUrhegyi] on Aug 14, 2018, 16:34

[Gitlab user @devcurmudgeon] OK, thanks for the feedback, agree that it's not overly welcoming for new users to have to read that and then go through those links (in fairness I did try to understand the specific tasks required to meet the outcomes of this request before i worked on it). So perhaps !657 doesn't close this but it might be one part of the overall story.

[Gitlab user @jjardon] I'm really not sure about that approach. It's precisely what I tried to avoid.

It would mean that we have to update the install guide in master (where the docs are built and deployed from), for every release made from the release branch - this does not make logistical sense at all.

I agree with [Gitlab user @tristanvb], the potential risk of things becoming out of sync here is huge.

[Cynical-Optimist]

In GitLab by [Gitlab user @jjardon] on Aug 14, 2018, 16:47

[Gitlab user @LaurenceUrhegyi] I agree with [Gitlab user @tristanvb] as well, but I consider this something absolutely critical for new users, so I'd prefer to assume that risk for now until we have the automation in place.

As he said at https://gitlab.com/BuildStream/buildstream/issues/528#note_92314309

With that said, it can be that we absolutely need a stop-gap solution until a website materializes;
in which case I have to concede that we need to pollute the history with this noise until we get a website.

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 22, 2018, 09:38

marked this issue as related to #587

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 22, 2018, 09:41

Noting here that I hope to fix #587 before the 1.2.0 release (which is in just 2 weeks), this will replace the git install method as the preferred method of installing BuildStream in the install guide, and will not require anyone to understand any branches or tags or suchlike.

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 25, 2018, 12:17

mentioned in commit e89e58bca71bc2cb1d4f641f9d4bf3185aaa4383

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 25, 2018, 12:42

mentioned in commit 0863256

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 26, 2018, 08:50

mentioned in commit 74e32d481c33673fc3b00ebddd14681e8b04acb2

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 26, 2018, 08:55

mentioned in commit 094b46929b6b0d4b49b765e6b84fd6483ea75edd

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 26, 2018, 08:58

mentioned in commit b46324cc8642784729e150a6bd48b3e02e9d1700

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 26, 2018, 09:16

mentioned in commit 0f32927

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 26, 2018, 09:17

mentioned in merge request !736

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 27, 2018, 10:39

Progress report

This is not completely fixed yet but here is an update on what has happened so far:

• !717: Added section to install guide for installing from PyPI

  Users who install from PyPI will automatically always get the latest recommended version, they should never have a need for understanding versions.

  Note that this is not a fully automated process because BuildStream does not only depend on pure python libraries, as such it still belongs in the installing from source section.

• !733: Refactor of install guide ToC and some additions

  • This adds a new section in the install guide, based on [Gitlab user @jjardon]'s earlier patch in !661

    I don't like that this section refers to git branches currently, we still need a clearer statement on what the latest tags are for releases and development snapshots

  • This branch separates the install guide sections for installing from source and installing directly from your distro.

    People running distros which have already packaged BuildStream don't need all the information needed for installing from source. Also, people who install via a distro package need not worry about the version at this point either, they will only get the latest recommended version that a distro was able to provide.

  • In the installation from source section, we've made the PyPI instruction "recommended", in fact any user who is not actually developing BuildStream, does not need to understand the versions in order to install the correct one; only people contributing to BuildStream should need to understand these things.

  • In the installation from git section, we've also linked to the new page about semantic versioning mentioned above, and explained that the user should checkout the desired tag before proceeding to install.

    This replaces [Gitlab user @LaurenceUrhegyi]'s new wording from his attempt in !657

• !736: Use stronger language in the README that users should follow the install guide

  Previously it just said "First install BuildStream and then follow our tutorial...",
  now we emphasize more that the user should follow the install guide:

  To get started, first install BuildStream by following the installation guide and then follow our tutorial in the user guide.

More stuff to do

• Implement an actual website for BuildStream, we shouldn't be over crowding the technical reference manual and user guides with things that belong on the website.

  The existing install guides should probably stay, but release announcements, news and "Downloads" section of a website will go a long way towards fixing this issue.

• Consider a custom badge

  I have a sneaky tricky idea which I will try to implement soon, but will require that at least when we build the documentation on gitlab, that we do so from a git repository.

  The idea runs as follows:

  • Have the documentation makefile generate two svgs, similar to the badges gitlab automatically generates, like the pipeline.svg.

    One "badge" will be a "release" badge, while the other will be a "snapshot" badge, this will be generated simply by checking the tags in the history and pulling out the latest even/odd minor point tags.

  • The generated badges will be published along with the documentation at buildstream.gitlab.io

  • These badges can be links to either the published release tarballs, or to specific tag urls on gitlab.com

  • The badges will then be embedded into the README page and also in the install guide

  • These will always be automatically updated to the latest release and latest development snapshot, every time a pipeline runs on the master branch.

I think that if we can get these last two things done, we can safely close this issue.

[Cynical-Optimist]

In GitLab by [Gitlab user @toscalix] on Aug 29, 2018, 09:29

assigned to [Gitlab user @toscalix]

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 29, 2018, 11:20

mentioned in commit cfe812d4321dd740ad4b4546388b9a375cfc9b67

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 29, 2018, 11:20

mentioned in commit d53c230e144f3f24465742f03f6ccd69c74e53d5

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 29, 2018, 11:20

mentioned in commit 93b3a1f00e08b801f81f515c137ab7c3971c9cbc

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 29, 2018, 11:46

mentioned in commit 29e7eea

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Aug 29, 2018, 11:46

mentioned in commit 2d52705

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Sep 4, 2018, 08:36

mentioned in merge request website!27

[Cynical-Optimist]

In GitLab by [Gitlab user @toscalix] on Sep 17, 2018, 09:21

Have we adressed this issue in the documentation?

[Cynical-Optimist]

In GitLab by [Gitlab user @toscalix] on Sep 17, 2018, 09:21

assigned to [Gitlab user @devcurmudgeon] and unassigned [Gitlab user @toscalix]

[Cynical-Optimist]

In GitLab by [Gitlab user @devcurmudgeon] on Sep 17, 2018, 11:19

https://wiki.gnome.org/Projects/BuildStream has "Install BuildStream and download sources." Why do I need to do both of those?

https://gitlab.com/BuildStream/buildstream tells me to go to https://buildstream.gitlab.io/buildstream/main_install.html which then has several links and two badges linking to different things.

https://buildstream.build/install.html has instructions that at least seem a bit better (I haven't tried them). However, given that the other pages still exist, readers can and will still get lost.

So no, I don't think we have.

[Cynical-Optimist]

In GitLab by [Gitlab user @devcurmudgeon] on Sep 17, 2018, 11:20

assigned to [Gitlab user @toscalix] and unassigned [Gitlab user @devcurmudgeon]

[Cynical-Optimist]

In GitLab by [Gitlab user @tristanvb] on Sep 17, 2018, 11:45

My view is that we have to wait until we are happy enough with the website, which should be this week, before we start updating links from various other sources to start pointing to it.

Once we have updated the links, we can come back and close this.

It looks like the wiki has been modified in advance of this, though, and I agree we should not have any link to the download page from there; just the install instructions are relevant; if the user chooses to install from a tarball (not recommended, except for distro package maintainers and the like), then they will find the download page through there.