[Mesa-dev] [PATCH 3/3] docs: document the staging branch and add reference to it

[Juan A. Suarez Romero]

On Thu, 2018-11-08 at 14:48 +0000, Emil Velikov wrote:
> On Thu, 8 Nov 2018 at 11:54, Juan A. Suarez Romero <jasuarez at igalia.com> wrote:
> > On Wed, 2018-11-07 at 16:02 +0000, Emil Velikov wrote:
> > > From: Emil Velikov <emil.velikov at collabora.com>
> > > 
> > > A while back we agreed that having a live/staging branch is beneficial.
> > > Sadly we forgot to document that, so here is my first attempt.
> > > 
> > > Document the caveat that the branch history is not stable.
> > > 
> > > CC: Andres Gomez <agomez at igalia.com>
> > > CC: Dylan Baker <dylan at pnwbakers.com>
> > > CC: Juan A. Suarez Romero <jasuarez at igalia.com>
> > > Signed-off-by: Emil Velikov <emil.velikov at collabora.com>
> > > ---
> > >  docs/releasing.html         | 20 ++++++++++++++++++++
> > >  docs/submittingpatches.html |  3 +++
> > >  2 files changed, 23 insertions(+)
> > > 
> > > diff --git a/docs/releasing.html b/docs/releasing.html
> > > index 87590b19301..8ebc2953366 100644
> > > --- a/docs/releasing.html
> > > +++ b/docs/releasing.html
> > > @@ -21,6 +21,7 @@
> > >  <li><a href="#overview">Overview</a>
> > >  <li><a href="#schedule">Release schedule</a>
> > >  <li><a href="#pickntest">Cherry-pick and test</a>
> > > +<li><a href="#stagingbranch">Staging branch</a>
> > >  <li><a href="#branch">Making a branchpoint</a>
> > >  <li><a href="#prerelease">Pre-release announcement</a>
> > >  <li><a href="#release">Making a new release</a>
> > > @@ -212,6 +213,25 @@ system and making some every day's use until the release may be a good
> > >  idea too.
> > >  </p>
> > > 
> > > +<h1 id="stagingbranch">Staging branch</h1>
> > > +
> > > +<p>
> > > +A live branch, which contains the currently merge/rejected patches is available
> > > +in the main repository under <code>staging/X.Y</code>. For example:
> > > +</p>
> > > +<pre>
> > > +     staging/18.1 - WIP branch for the 18.1 series
> > > +     staging/18.2 - WIP branch for the 18.2 series
> > > +</pre>
> > > +
> > > +<p>
> > > +Notes:
> > > +</p>
> > > +<ul>
> > > +<li>People are encouraged to test the branch and report regressions.</li>
> > 
> > I'd say "people are encouraged to test the staging branch and report
> > regressions."
> > 
> Ack.
> 
> > > +<li>The branch history is not stable and it <strong>will</strong> be rebased,</li>
> > 
> > I'd say it "could be rebased", rather than "will be rebased".
> > 
> I'd rather keep the explicit and bold will. It makes it clear and
> obvious that basing work on top of the branch is a bad idea.
> Even if it doesn't get rebased that often.
> 

That's why I suggest to change "will" by "could". In both cases means that
basing work on top is not a good idea. But "could" explicitly states that it is
up to us to rebase or not; sometimes we will rebase, other times we won't.

> > With the above changes, the series is:
> > 
> > Reviewed-by: Juan A. Suarez <jasuarez at igalia.com>
> > 
> Thanks. Let me know if you're OK with my reply on the latter suggestion.

As it is a minor issue, I'm OK if you still want to go ahead with your
suggestion. 


> 
> -Emil
>