Proposal - using an RFC system for design discussions

Development
1

Hi all,

(TL;DR: Is [0] a good idea?)

For a while now, I've been thinking about the issue of open design process,
and how we can take the design discussion forward (Dominic sent me this
excellent post[1] on the subject a while back - thanks!). I'd like to
illustrate the current problems and a possible solution.

The issues

··· ----------

Currently we have 3 main issues with our design process:

  • Closed discussion
  • Fragmented discussion
  • Lack of review of design

Let me take these one-by-one. Firstly, closed discussion - of the people we
might call “core devs”, many work together in the same offices. That’s not
an
inherently bad thing, but it does lead to hallway-track discussion. One
example would be the recent surge of smart-proxy features, for example (I’ll
stress that I’m not attacking anyone here - these were good additions, it’s
simply that the way in which they arrived caused some friction).

I think we should be taking this to the next level by moving the design
discussion out into the dev community wherever possible. This is something
we’re
already getting better at, but it’s held back by the other two points (e.g.
I
frequently hear the comment - why take a design to the community if no-one
reviews it there?)

Second, fragmented discussion - we have no official place to discuss design.
Some people like to use tracker issues in Redmine. Others prefer to prepare
example code as a GitHub PR. Still others like to discuss on the mailing
list.
None of these are used coherently, and none really provide an easy way to
see,
historically, why a feature was implemented in the way it was, with all
the
discussion about pitfalls, possible alternatives, etc.

Third, lack of design reviews - this is a consequence of the fragmentation.
There’s no consistent place for interested people to look for current
proposals, and to see what designs are under consideration. Redmine and
GitHub
are too noisy with the day-to-day commits of bugfixes, small improvements,
etc,
and have too many repos to track. The mailing list is better, but it’s not a
great medium for historical data, and still gets a bit noisy at times,
leading
to design reviews getting missed.

The proposal

I’m seeing more and more projects implementing a RFC repo in their
source control. This is a very simple repo containing a README for
instructions, and a directory full of existing RFCs, and perhaps a table
listing current state of the open RFCs.

The process seems to be fairly simple - anyone can copy the template RFC to
a
new file, fill it out and submit a PR to the repo. From there a core dev
who is
familiar with that area can take on the role of mentor for the RFC, helping
it
to move forward, drive discussion, etc. Ultimately a decision will have to
be
taken about whether to accept an RFC, or reject it. It’s also acceptable to
discuss possible RFCs and implementations on the dev mailing list
beforehand.

The benefits here are:

  • Open design discussion
  • A single repo for interested-but-time-pressured community members to watch
  • Clear historical data on why features were done a certain way
    • Use cases, user stories, pitfalls can all be recorded for future info
  • Some form of roadmap information for interested parties (not binding, but
    at
    least an indication of intent)

There is one minor downside, and that’s a slight overhead in reviewing these
RFCs - but I think the benefits to the project of a clear design system
outweighs this heavily. I expect most RFCs, initially at least, to be coming
from existing developers who will be quite capable of mentoring their own
RFCs, so that shouldn’t add much.

I’ve put together a sample RFC repo at https://github.com/GregSutcliffe/rfcs

please do take a look at the process in the README, the RFC template, and
I’ve
filled one RFC example out (the host/nic changes that went into 1.8, written
from my memory). This is based on the RFC repos from Rust[2] and EmberJS[3].
I’ll be happy to transfer ownership of this to theforeman/rfcs if the
proposal
is successful, or we can write a new one - either way, I’m sure there’ll be
changes.

I see this as being relevant for all the Foreman repos, although plugins
can,
of course, choose to opt out or set up their own RFC system. I’ve left
plugin
RFCs deliberately vague in the document for now - I can see plugins perhaps
adding RFCs to their own repo, or having a separate directory in the main
rfcs
repo. Thoughts welcome!

Thanks for reading to the end! Comments are most definitely encouraged :slight_smile:

[0] https://github.com/GregSutcliffe/rfcs
[1] http://dtrace.org/blogs/bmc/2015/09/16/requests-for-discussion/
[2] https://github.com/rust-lang/rfcs/blob/master/README.md
[3] https://github.com/emberjs/rfcs/blob/master/README.md

2

Very interesting idea! Not surprisingly, the Pulp community has similar
challenges, and I think a process like this might be a good fit for us too.

I quickly started thinking about the challenges of managing hundreds or
thousands of RFCs. What if I want to search for an old one, display only
ones in a particular state, formally request that an individual respond to
a question on one, link an RFC with one or more user stories in the issue
tracker, etc. How do you maintain the master index? Using github pull
requests to manage the lifecycle of an RFC is effective, and a workflow
that feels natural to developers, but is it worth considering a tool that's
explicitly designed to make all of these things easy?

Like Redmine! You could create a new "tracker" [0] for RFCs, give it an
appropriate list of states, and have a feature-rich RFC management system
that's fully integrated with your existing issue tracking system.

In addition to making the above workflows easy, it makes participation
easier for community members who are not developers, and thus may not be as
comfortable with pull requests.

What do you all think of that? Pros/cons of using redmine vs. github?

[0] "Trackers are how you split your issues into different types - common
ones are Bug, Feature, Defect or etc."
http://www.redmine.org/projects/redmine/wiki/RedmineIssueTrackingSetup

Michael

··· On Tuesday, April 12, 2016 at 9:27:44 AM UTC-4, Greg Sutcliffe wrote: > > Hi all, > > (TL;DR: Is [0] a good idea?) > > For a while now, I've been thinking about the issue of open design process, > and how we can take the design discussion forward (Dominic sent me this > excellent post[1] on the subject a while back - thanks!). I'd like to > illustrate the current problems and a possible solution. > > The issues > ---------- > > Currently we have 3 main issues with our design process: > > * Closed discussion > * Fragmented discussion > * Lack of review of design > > Let me take these one-by-one. Firstly, closed discussion - of the people we > might call "core devs", many work together in the same offices. That's not > an > inherently bad thing, but it *does* lead to hallway-track discussion. One > example would be the recent surge of smart-proxy features, for example > (I'll > stress that I'm not attacking anyone here - these were good additions, it's > simply that the *way* in which they arrived caused some friction). > > I think we should be taking this to the next level by moving the design > discussion out into the dev community wherever possible. This is something > we're > already getting better at, but it's held back by the other two points > (e.g. I > frequently hear the comment - why take a design to the community if no-one > reviews it there?) > > Second, fragmented discussion - we have no official place to discuss > design. > Some people like to use tracker issues in Redmine. Others prefer to prepare > example code as a GitHub PR. Still others like to discuss on the mailing > list. > None of these are used coherently, and none really provide an easy way to > see, > historically, why a feature was implemented *in the way it was*, with all > the > discussion about pitfalls, possible alternatives, etc. > > Third, lack of design reviews - this is a consequence of the fragmentation. > There's no consistent place for interested people to look for current > proposals, and to see what designs are under consideration. Redmine and > GitHub > are too noisy with the day-to-day commits of bugfixes, small improvements, > etc, > and have too many repos to track. The mailing list is better, but it's not > a > great medium for historical data, and still gets a bit noisy at times, > leading > to design reviews getting missed. > > The proposal > --- > > I'm seeing more and more projects implementing a RFC repo in their > source control. This is a *very* simple repo containing a README for > instructions, and a directory full of existing RFCs, and perhaps a table > listing current state of the open RFCs. > > The process seems to be fairly simple - anyone can copy the template RFC > to a > new file, fill it out and submit a PR to the repo. From there a core dev > who is > familiar with that area can take on the role of mentor for the RFC, > helping it > to move forward, drive discussion, etc. Ultimately a decision will have to > be > taken about whether to accept an RFC, or reject it. It's also acceptable to > discuss possible RFCs and implementations on the dev mailing list > beforehand. > > The benefits here are: > > * Open design discussion > * A single repo for interested-but-time-pressured community members to > watch > * Clear historical data on why features were done a certain way > * Use cases, user stories, pitfalls can all be recorded for future info > * Some form of roadmap information for interested parties (not binding, > but at > least an indication of intent) > > There is one minor downside, and that's a slight overhead in reviewing > these > RFCs - but I think the benefits to the project of a clear design system > outweighs this heavily. I expect most RFCs, initially at least, to be > coming > from existing developers who will be quite capable of mentoring their *own* > RFCs, so that shouldn't add much. > > I've put together a sample RFC repo at > https://github.com/GregSutcliffe/rfcs - > please do take a look at the process in the README, the RFC template, and > I've > filled one RFC example out (the host/nic changes that went into 1.8, > written > from my memory). This is based on the RFC repos from Rust[2] and > EmberJS[3]. > I'll be happy to transfer ownership of this to theforeman/rfcs if the > proposal > is successful, or we can write a new one - either way, I'm sure there'll > be changes. > > I see this as being relevant for all the Foreman repos, although plugins > can, > of course, choose to opt out or set up their own RFC system. I've left > plugin > RFCs deliberately vague in the document for now - I can see plugins perhaps > adding RFCs to their own repo, or having a separate directory in the main > rfcs > repo. Thoughts welcome! > > Thanks for reading to the end! Comments are most definitely encouraged :) > > [0] https://github.com/GregSutcliffe/rfcs > [1] http://dtrace.org/blogs/bmc/2015/09/16/requests-for-discussion/ > [2] https://github.com/rust-lang/rfcs/blob/master/README.md > [3] https://github.com/emberjs/rfcs/blob/master/README.md >
3

> Hi all,
>
> (TL;DR: Is [0] a good idea?)

+1 yes please

I'd desire it standardized across major plugins as well (salt, rex, etc.) and hammer too.

··· ----- Original Message -----

For a while now, I’ve been thinking about the issue of open design process,
and how we can take the design discussion forward (Dominic sent me this
excellent post[1] on the subject a while back - thanks!). I’d like to
illustrate the current problems and a possible solution.

The issues

Currently we have 3 main issues with our design process:

  • Closed discussion
  • Fragmented discussion
  • Lack of review of design

Let me take these one-by-one. Firstly, closed discussion - of the people we
might call “core devs”, many work together in the same offices. That’s not
an
inherently bad thing, but it does lead to hallway-track discussion. One
example would be the recent surge of smart-proxy features, for example (I’ll
stress that I’m not attacking anyone here - these were good additions, it’s
simply that the way in which they arrived caused some friction).

I think we should be taking this to the next level by moving the design
discussion out into the dev community wherever possible. This is something
we’re
already getting better at, but it’s held back by the other two points (e.g.
I
frequently hear the comment - why take a design to the community if no-one
reviews it there?)

Second, fragmented discussion - we have no official place to discuss design.
Some people like to use tracker issues in Redmine. Others prefer to prepare
example code as a GitHub PR. Still others like to discuss on the mailing
list.
None of these are used coherently, and none really provide an easy way to
see,
historically, why a feature was implemented in the way it was, with all
the
discussion about pitfalls, possible alternatives, etc.

Third, lack of design reviews - this is a consequence of the fragmentation.
There’s no consistent place for interested people to look for current
proposals, and to see what designs are under consideration. Redmine and
GitHub
are too noisy with the day-to-day commits of bugfixes, small improvements,
etc,
and have too many repos to track. The mailing list is better, but it’s not a
great medium for historical data, and still gets a bit noisy at times,
leading
to design reviews getting missed.

The proposal

I’m seeing more and more projects implementing a RFC repo in their
source control. This is a very simple repo containing a README for
instructions, and a directory full of existing RFCs, and perhaps a table
listing current state of the open RFCs.

The process seems to be fairly simple - anyone can copy the template RFC to
a
new file, fill it out and submit a PR to the repo. From there a core dev
who is
familiar with that area can take on the role of mentor for the RFC, helping
it
to move forward, drive discussion, etc. Ultimately a decision will have to
be
taken about whether to accept an RFC, or reject it. It’s also acceptable to
discuss possible RFCs and implementations on the dev mailing list
beforehand.

The benefits here are:

  • Open design discussion
  • A single repo for interested-but-time-pressured community members to watch
  • Clear historical data on why features were done a certain way
    • Use cases, user stories, pitfalls can all be recorded for future info
  • Some form of roadmap information for interested parties (not binding, but
    at
    least an indication of intent)

There is one minor downside, and that’s a slight overhead in reviewing these
RFCs - but I think the benefits to the project of a clear design system
outweighs this heavily. I expect most RFCs, initially at least, to be coming
from existing developers who will be quite capable of mentoring their own
RFCs, so that shouldn’t add much.

I’ve put together a sample RFC repo at GitHub - GregSutcliffe/rfcs: RFCs for TheForeman

please do take a look at the process in the README, the RFC template, and
I’ve
filled one RFC example out (the host/nic changes that went into 1.8, written
from my memory). This is based on the RFC repos from Rust[2] and EmberJS[3].
I’ll be happy to transfer ownership of this to theforeman/rfcs if the
proposal
is successful, or we can write a new one - either way, I’m sure there’ll be
changes.

I see this as being relevant for all the Foreman repos, although plugins
can,
of course, choose to opt out or set up their own RFC system. I’ve left
plugin
RFCs deliberately vague in the document for now - I can see plugins perhaps
adding RFCs to their own repo, or having a separate directory in the main
rfcs
repo. Thoughts welcome!

Thanks for reading to the end! Comments are most definitely encouraged :slight_smile:

[0] GitHub - GregSutcliffe/rfcs: RFCs for TheForeman
[1] Requests for discussion – The Observation Deck
[2] rfcs/README.md at master · rust-lang/rfcs · GitHub
[3] rfcs/README.md at master · emberjs/rfcs · GitHub

–
You received this message because you are subscribed to the Google Groups
“foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

4

> Hi all,
>
> (TL;DR: Is [0] a good idea?)
>
> For a while now, I've been thinking about the issue of open design process,
> and how we can take the design discussion forward (Dominic sent me this
> excellent post[1] on the subject a while back - thanks!).

To be clear to my position, I was only linking to the page - I don't
think I'm in favour of adding such a process to Foreman.

··· On 12/04/16 14:27, Greg Sutcliffe wrote:

[1] Requests for discussion – The Observation Deck

–
Dominic Cleal
dominic@cleal.org

5

> Hi all,
>
> (TL;DR: Is [0] a good idea?)
>
> For a while now, I've been thinking about the issue of open design process,
> and how we can take the design discussion forward (Dominic sent me this
> excellent post[1] on the subject a while back - thanks!). I'd like to
> illustrate the current problems and a possible solution.
>
> The issues
> ----------
>
> Currently we have 3 main issues with our design process:
>
> is it really a design issue? or rather a change (most likely we both mean
the same thing) ? for the rest of the thread I'm going to assume this is
about changes in general (ones that usually requires a discussion / core
team agreement prior to code).

  • Closed discussion
    > * Fragmented discussion
    > * Lack of review of design
    >

I would also add, lack of visibility (e.g. if a random contributor wants to
know what other people want to see changes next etc) and the fact that many
mails go to die in the dev list.

>
> Let me take these one-by-one. Firstly, closed discussion - of the people we
> might call "core devs", many work together in the same offices. That's not
> an
> inherently bad thing, but it does lead to hallway-track discussion. One
> example would be the recent surge of smart-proxy features, for example
> (I'll
> stress that I'm not attacking anyone here - these were good additions, it's
> simply that the way in which they arrived caused some friction).
>
> I think we should be taking this to the next level by moving the design
> discussion out into the dev community wherever possible. This is something
> we're
> already getting better at, but it's held back by the other two points
> (e.g. I
> frequently hear the comment - why take a design to the community if no-one
> reviews it there?)
>
> Second, fragmented discussion - we have no official place to discuss
> design.
> Some people like to use tracker issues in Redmine. Others prefer to prepare
> example code as a GitHub PR. Still others like to discuss on the mailing
> list.
> None of these are used coherently, and none really provide an easy way to
> see,
> historically, why a feature was implemented in the way it was, with all
> the
> discussion about pitfalls, possible alternatives, etc.
>
> Third, lack of design reviews - this is a consequence of the fragmentation.
> There's no consistent place for interested people to look for current
> proposals, and to see what designs are under consideration. Redmine and
> GitHub
> are too noisy with the day-to-day commits of bugfixes, small improvements,
> etc,
> and have too many repos to track. The mailing list is better, but it's not
> a
> great medium for historical data, and still gets a bit noisy at times,
> leading
> to design reviews getting missed.
>
> The proposal
> —
>
> I'm seeing more and more projects implementing a RFC repo in their
> source control. This is a very simple repo containing a README for
> instructions, and a directory full of existing RFCs, and perhaps a table
> listing current state of the open RFCs.
>
> The process seems to be fairly simple - anyone can copy the template RFC
> to a
> new file, fill it out and submit a PR to the repo. From there a core dev
> who is
> familiar with that area can take on the role of mentor for the RFC,
> helping it
> to move forward, drive discussion, etc. Ultimately a decision will have to
> be
> taken about whether to accept an RFC, or reject it. It's also acceptable to
> discuss possible RFCs and implementations on the dev mailing list
> beforehand.
>
> The benefits here are:
>
> * Open design discussion
> * A single repo for interested-but-time-pressured community members to
> watch
> * Clear historical data on why features were done a certain way
> * Use cases, user stories, pitfalls can all be recorded for future info
> * Some form of roadmap information for interested parties (not binding,
> but at
> least an indication of intent)
>
> There is one minor downside, and that's a slight overhead in reviewing
> these
> RFCs - but I think the benefits to the project of a clear design system
> outweighs this heavily. I expect most RFCs, initially at least, to be
> coming
> from existing developers who will be quite capable of mentoring their own
> RFCs, so that shouldn't add much.
>
> I've put together a sample RFC repo at
> GitHub - GregSutcliffe/rfcs: RFCs for TheForeman -
> please do take a look at the process in the README, the RFC template, and
> I've
> filled one RFC example out (the host/nic changes that went into 1.8,
> written
> from my memory). This is based on the RFC repos from Rust[2] and
> EmberJS[3].
> I'll be happy to transfer ownership of this to theforeman/rfcs if the
> proposal
> is successful, or we can write a new one - either way, I'm sure there'll
> be changes.
>
> I see this as being relevant for all the Foreman repos, although plugins
> can,
> of course, choose to opt out or set up their own RFC system. I've left
> plugin
> RFCs deliberately vague in the document for now - I can see plugins perhaps
> adding RFCs to their own repo, or having a separate directory in the main
> rfcs
> repo. Thoughts welcome!
>
> Thanks for reading to the end! Comments are most definitely encouraged :slight_smile:
>

big +1 from my side, I think this clearly helps allowing people to share
ideas and raise concerns early in the process.
i think using github pull requests makes a lot of sense as well, and I
expect to see similar benefits as we migrated the blog to pull request
based as well.

Ohad

··· On Tue, Apr 12, 2016 at 4:27 PM, Greg Sutcliffe wrote:

[0] GitHub - GregSutcliffe/rfcs: RFCs for TheForeman
[1] Requests for discussion – The Observation Deck
[2] rfcs/README.md at master · rust-lang/rfcs · GitHub
[3] rfcs/README.md at master · emberjs/rfcs · GitHub

–
You received this message because you are subscribed to the Google Groups
“foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

6

> To be clear to my position, I was only linking to the page

Apologies, my intent was to give credit where credit is due, not to
misrepresent.

> I'd desire it standardized across major plugins as well (salt, rex, etc.)
and hammer too.

I don't think it can be mandated but plugins can and should be welcomed
into this repo. We've had cases of big changes affecting core + plugins
together, or a desired feature in a plugin requiring core changes. This
process is by design cross-repo and we should take advantage of that.

>
> I quickly started thinking about the challenges of managing hundreds or
thousands of RFCs.

I really doubt it'll get to that number, especially that number of
unimplemented ones. My inspiration comes from a JS framework and a coding
language, and even they haven't got any where near thousands (Ember is
actually only about 20, in a year and a half).

> What do you all think of that? Pros/cons of using redmine vs. github?

Good points. As I mentioned in my opening statement (and paraphrased from
[1]) I believe Redmine is simply too noisy with all its existing traffic.
Let me see how I might address your points in Git :slight_smile:

  • search for an old one
    • text search is easy, as are the links to Redmine. Google makes this
      trivial [4]
  • display only ones in a particular state
    • there are only three states (open, rejected, accepted):
      • accepted ones are in text/ in the repo
      • open are simply open PRs
      • rejected have been closed without merge, search for "is:pr is:closed
        is:unmerged"
  • formally request that an individual respond to a question on one
    • I would expect authors to monitor their RFC for comments, but GitHub's
      @name syntax
      does send a notification to the user
  • link an RFC with one or more user stories in the issue tracker
    • Further commits to the repo to add links to relevant tickets are
      entirely welcome. I'd
      advocate use of a tracker ticket in Redmine that holds the other
      tickets (eg #2409)
  • How do you maintain the master index?
    • Open to debate. Ember just links to the text/ directory for example
      [5]. Anything in
      there is accepted, by definition, and I quite like that.

In addition, Trackers are a ticket type - are you also proposing a new
Project as well? Otherwise we don't get the cross-repo benefits I mention
above in reply to Tom. With a new Project, Redmine could work, but with
Git (not necessarily GitHub) you get to easily see the revision history of
the RFC. Redmine can do that but it's much less readable I think (e.g.
[6]). Given an RFC is likely to go through changes as it's discussed, that
history is important - in a year's time, we may want to know how & why we
reached a certain decision. This goes double if we choose rebase-nosquash
as our default merge strategy for this repo - then all the commits in the
PR are preserved and are readable from the History button on any RFC's page.

> It makes participation easier for community members who are not
developers, and thus may not be as comfortable with pull requests.

GitHub has long had the "New file" button in the WebUI - for those not
comfortable with Git, they can be directed to this button and told to copy
the contents of 0000-template.md

[4]
https://encrypted.google.com/search?hl=en&q=ember%20js%20rfcs#hl=en&q=ember+js+rfc+0015
[5] https://github.com/emberjs/rfcs/blame/master/README.md#L13
[6] Feature #14396: Support for subnet options inside "pool" blocks - Smart Proxy - Foreman

··· On 12 April 2016 at 15:02, Dominic Cleal wrote: On 12 April 2016 at 15:14, Tom McKay wrote: On 12 April 2016 at 16:17, Michael Hrivnak wrote:

–
Greg

7

> (TL;DR: Is [0] a good idea?)

I would like to mention first, that we already have such a thing. It
is my attempt to do the very same, inspired by oVirt team. They maintain
Wiki which seems to be quite appropriate for this purpose (quick edits,
good formatting), and we have it here:

http://projects.theforeman.org/projects/foreman/wiki/Features

Unfortunately, I did not find a way how to create a list of sub-pages on
a RedMine wiki page, so it's not that transparent. An example entry is
here:

http://projects.theforeman.org/projects/foreman/wiki/CentralizedLogging

To the date, we have six feature designs on the wiki. The lack of the
index page is perhaps the reason why this failed. It definitely needs
more transparency.

I am not against the new RFC repo, in case plugins are allowed to use
it. Creating RFC repos for each plugin or component would make things
actually worse. But I share skepticism here, I am not sure if it helps
to improve things. I already sent two reminders to the list about
putting new features on our Wiki.

If we are able to do the same, but on our Wiki, I lean towards this
because to me it's more convenient way of editing the stuff.

··· -- Later, Lukas #lzap Zapletal
8

the same thing) ?

I think we probably do mean the same thing, yes. I'm talking about design
in the purest sense - from the dictionary:

  1. (verb) to prepare the preliminary plans for (a work to be executed)

In this context, I thing "design" and "change" are equivalent.

··· On 12 April 2016 at 14:38, Ohad Levy wrote: > is it really a design issue? or rather a change (most likely we both mean
9

> > Hi all,
> >
> > (TL;DR: Is [0] a good idea?)
> >
> > For a while now, I've been thinking about the issue of open design
> process,
> > and how we can take the design discussion forward (Dominic sent me this
> > excellent post[1] on the subject a while back - thanks!).
>
> To be clear to my position, I was only linking to the page - I don't
> think I'm in favour of adding such a process to Foreman.
>

can you elaborate more on why?

thanks,
Ohad

··· On Tue, Apr 12, 2016 at 5:02 PM, Dominic Cleal wrote: > On 12/04/16 14:27, Greg Sutcliffe wrote:

[1] Requests for discussion – The Observation Deck

–
Dominic Cleal
dominic@cleal.org

–
You received this message because you are subscribed to the Google Groups
“foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

10

What I like about github is that the RFC would, I assume, be a PR until interested parties could ack it (or majority acked it, or whatever groundrules are established). As a PR comments would be at contextual locations in the document so conversations could happen in-place. I don't necessarily think github is the best tool for this but it would, in my opinion, be a step above the static wiki and the unresponsive dev email list. Plus, if a RFC was opened, comments addressed, and finalized I would consider that to be a community mandate for the project's approach when later actual code PRs were being picked at by those that failed to participate in the earlier design process. Seems much more open and accessible.

··· ----- Original Message ----- > > (TL;DR: Is [0] a good idea?) > > I would like to mention first, that we already *have* such a thing. It > is my attempt to do the very same, inspired by oVirt team. They maintain > Wiki which seems to be quite appropriate for this purpose (quick edits, > good formatting), and we have it here: > > http://projects.theforeman.org/projects/foreman/wiki/Features > > Unfortunately, I did not find a way how to create a list of sub-pages on > a RedMine wiki page, so it's not that transparent. An example entry is > here: > > http://projects.theforeman.org/projects/foreman/wiki/CentralizedLogging > > To the date, we have six feature designs on the wiki. The lack of the > index page is perhaps the reason why this failed. It definitely needs > more transparency. > > I am not against the new RFC repo, in case plugins are allowed to use > it. Creating RFC repos for each plugin or component would make things > actually worse. But I share skepticism here, I am not sure if it helps > to improve things. I already sent two reminders to the list about > putting new features on our Wiki. > > If we are able to do the same, but on our Wiki, I lean towards this > because to me it's more convenient way of editing the stuff. > > -- > Later, > Lukas #lzap Zapletal > > -- > You received this message because you are subscribed to the Google Groups > "foreman-dev" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to foreman-dev+unsubscribe@googlegroups.com. > For more options, visit https://groups.google.com/d/optout. >
11

+1 for giving a RFC github repo a try. I believe that github has bigger
chances to be adopted. People use it daily and the UI is very clean to
comment and review the changes too.

I'm also for using one repo for the core and plugins. Bigger changes
affect multiple areas which will be easier to track at one place.

T.

··· On 04/13/2016 11:50 AM, Lukas Zapletal wrote: >> (TL;DR: Is [0] a good idea?) > > I would like to mention first, that we already *have* such a thing. It > is my attempt to do the very same, inspired by oVirt team. They maintain > Wiki which seems to be quite appropriate for this purpose (quick edits, > good formatting), and we have it here: > > http://projects.theforeman.org/projects/foreman/wiki/Features > > Unfortunately, I did not find a way how to create a list of sub-pages on > a RedMine wiki page, so it's not that transparent. An example entry is > here: > > http://projects.theforeman.org/projects/foreman/wiki/CentralizedLogging > > To the date, we have six feature designs on the wiki. The lack of the > index page is perhaps the reason why this failed. It definitely needs > more transparency. > > I am not against the new RFC repo, in case plugins are allowed to use > it. Creating RFC repos for each plugin or component would make things > actually worse. But I share skepticism here, I am not sure if it helps > to improve things. I already sent two reminders to the list about > putting new features on our Wiki. > > If we are able to do the same, but on our Wiki, I lean towards this > because to me it's more convenient way of editing the stuff. >
12

We've got plenty of tools (this mailing list, tickets, a wiki) that
aren't being used properly without adding another tool and process. I
don't think adding another method is necessary to create more content or
discussion about a change.

··· On 12/04/16 15:11, Ohad Levy wrote: > > > On Tue, Apr 12, 2016 at 5:02 PM, Dominic Cleal > wrote: > > On 12/04/16 14:27, Greg Sutcliffe wrote: > > Hi all, > > > > (TL;DR: Is [0] a good idea?) > > > > For a while now, I've been thinking about the issue of open design process, > > and how we can take the design discussion forward (Dominic sent me this > > excellent post[1] on the subject a while back - thanks!). > > To be clear to my position, I was only linking to the page - I don't > think I'm in favour of adding such a process to Foreman. > > > can you elaborate more on why?

–
Dominic Cleal
dominic@cleal.org

13

>
>> (TL;DR: Is [0] a good idea?)
>>>
>>
>> I would like to mention first, that we already have such a thing. It
>> is my attempt to do the very same, inspired by oVirt team. They maintain
>> Wiki which seems to be quite appropriate for this purpose (quick edits,
>> good formatting), and we have it here:
>>
>> http://projects.theforeman.org/projects/foreman/wiki/Features
>>
>> Unfortunately, I did not find a way how to create a list of sub-pages on
>> a RedMine wiki page, so it's not that transparent. An example entry is
>> here:
>>
>> http://projects.theforeman.org/projects/foreman/wiki/CentralizedLogging
>>
>> To the date, we have six feature designs on the wiki. The lack of the
>> index page is perhaps the reason why this failed. It definitely needs
>> more transparency.
>>
>> I am not against the new RFC repo, in case plugins are allowed to use
>> it. Creating RFC repos for each plugin or component would make things
>> actually worse. But I share skepticism here, I am not sure if it helps
>> to improve things. I already sent two reminders to the list about
>> putting new features on our Wiki.
>>
>> If we are able to do the same, but on our Wiki, I lean towards this
>> because to me it's more convenient way of editing the stuff.
>>
>>
> +1 for giving a RFC github repo a try. I believe that github has bigger
> chances to be adopted. People use it daily and the UI is very clean to
> comment and review the changes too.
>

For me, as Tomas says, the key here is "giving…a try". We have a few
tools, and a few methods at our disposal that have largely been tried for
managing large features or discussions. And yet, we go round and round
because, as Greg points out, the real problem is not being solved with
respect to designs. I believe it behooves us to try something else. If it
fails, at least we experimented, gave it a shot and we try something else
to find what works for us. If it works, then bravo. There is no silver
bullet, but the trick is trying something until we find what works by and
large.

Apologies if I am restating what has already been said, but the questions I
have seen plague us are:

a) How to present a design with text, images, presentations, media, links?
b) How to solicit feedback on a design document?
c) How, as someone reviewing a design, do I give feedback?

The key, to me, is the last question because that is how designs get better
and help you to avoid finding issues further into the process where the
cost increases ten-fold with each step. Let's walk through some example
workflows using our tools.

Wiki:

  1. Create wiki page
  2. Add text, sections, links, media, images, etc.
  3. Send email to list announcing design
  4. Users and devs go to Redmine and post comments? Do they reply to the
    email thread? How do they reference pieces of the design?
  5. Comments iterated on
  6. Email sent saying hey design got updated
  7. Rinse and repeat 4-7

Email:

  1. Write up design within the confines of an email with text and links,
    find somewhere to host images or media to reference
  2. Send email to users? to dev? to both? cross-post?
  3. Users and devs reply to email, inline comments allow commenting on
    specific sections
  4. At some point, comments are waded through and a new email is sent with
    updated design
  5. Rinse and repeat

GIthub RFC

  1. Write up document with text, sections, links, media, references, images
  2. Open PR to RFC repo
  3. Send email noting a new design is ready for comment
  4. Users and devs go to PR and post comments directly to design
  5. Design is iterated on and new version is pushed to the PR
  6. Email sent noting updated design

Wiki and email suffer from a common flaw – how do I see what parts of the
design were updated between iterations easily so I can focus on the parts I
care about? For me, that is the nice part of the RFC repository, we take
the same workflow we use for code and apply it to designs.

Eric

··· On Wed, Apr 13, 2016 at 10:37 AM, Tomas Strachota wrote: > On 04/13/2016 11:50 AM, Lukas Zapletal wrote:

I’m also for using one repo for the core and plugins. Bigger changes
affect multiple areas which will be easier to track at one place.

T.

–
You received this message because you are subscribed to the Google Groups
“foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

–
Eric D. Helms
Red Hat Engineering
Ph.D. Student - North Carolina State University

14

>
>
>
>
> (TL;DR: Is [0] a good idea?)
>
>
> I would like to mention first, that we already have such a
> thing. It
> is my attempt to do the very same, inspired by oVirt team. They
> maintain
> Wiki which seems to be quite appropriate for this purpose (quick
> edits,
> good formatting), and we have it here:
>
> http://projects.theforeman.org/projects/foreman/wiki/Features
>
> Unfortunately, I did not find a way how to create a list of
> sub-pages on
> a RedMine wiki page, so it's not that transparent. An example
> entry is
> here:
>
> http://projects.theforeman.org/projects/foreman/wiki/CentralizedLogging
>
> To the date, we have six feature designs on the wiki. The lack
> of the
> index page is perhaps the reason why this failed. It definitely
> needs
> more transparency.
>
> I am not against the new RFC repo, in case plugins are allowed
> to use
> it. Creating RFC repos for each plugin or component would make
> things
> actually worse. But I share skepticism here, I am not sure if it
> helps
> to improve things. I already sent two reminders to the list about
> putting new features on our Wiki.
>
> If we are able to do the same, but on our Wiki, I lean towards this
> because to me it's more convenient way of editing the stuff.
>
>
> +1 for giving a RFC github repo a try. I believe that github has
> bigger chances to be adopted. People use it daily and the UI is very
> clean to comment and review the changes too.
>
>
>
> For me, as Tomas says, the key here is "giving…a try". We have a few
> tools, and a few methods at our disposal that have largely been tried
> for managing large features or discussions. And yet, we go round and
> round because, as Greg points out, the real problem is not being solved
> with respect to designs. I believe it behooves us to try something else.
> If it fails, at least we experimented, gave it a shot and we try
> something else to find what works for us. If it works, then bravo. There
> is no silver bullet, but the trick is trying something until we find
> what works by and large.
>
> Apologies if I am restating what has already been said, but the
> questions I have seen plague us are:
>
> a) How to present a design with text, images, presentations, media, links?
> b) How to solicit feedback on a design document?
> c) How, as someone reviewing a design, do I give feedback?
>
> The key, to me, is the last question because that is how designs get
> better and help you to avoid finding issues further into the process
> where the cost increases ten-fold with each step. Let's walk through
> some example workflows using our tools.
>
> Wiki:
>
> 1) Create wiki page
> 2) Add text, sections, links, media, images, etc.
> 3) Send email to list announcing design
> 4) Users and devs go to Redmine and post comments? Do they reply to the
> email thread? How do they reference pieces of the design?
> 5) Comments iterated on
> 6) Email sent saying hey design got updated
> 7) Rinse and repeat 4-7
>
> Email:
>
> 1) Write up design within the confines of an email with text and
> links, find somewhere to host images or media to reference
> 2) Send email to users? to dev? to both? cross-post?
> 3) Users and devs reply to email, inline comments allow commenting on
> specific sections
> 4) At some point, comments are waded through and a new email is sent
> with updated design
> 5) Rinse and repeat
>
> GIthub RFC
>
> 1) Write up document with text, sections, links, media, references, images
> 2) Open PR to RFC repo
> 3) Send email noting a new design is ready for comment
> 4) Users and devs go to PR and post comments directly to design
> 5) Design is iterated on and new version is pushed to the PR
> 6) Email sent noting updated design
>
>
> Wiki and email suffer from a common flaw – how do I see what parts of
> the design were updated between iterations easily so I can focus on the
> parts I care about? For me, that is the nice part of the RFC repository,
> we take the same workflow we use for code and apply it to designs.

I would also add that email has the drawback in that the discussion can
get very very large very quickly and its hard to see where things landed
and for discussions to get out off topic or into crazy ideas that may
never happen.

-Justin

··· On 04/13/2016 11:37 AM, Eric D Helms wrote: > On Wed, Apr 13, 2016 at 10:37 AM, Tomas Strachota > wrote: > On 04/13/2016 11:50 AM, Lukas Zapletal wrote:

Eric

I'm also for using one repo for the core and plugins. Bigger changes
affect multiple areas which will be easier to track at one place.

T.


-- 
You received this message because you are subscribed to the Google
Groups "foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it,
send an email to foreman-dev+unsubscribe@googlegroups.com
<mailto:foreman-dev%2Bunsubscribe@googlegroups.com>.
For more options, visit https://groups.google.com/d/optout.

–
Eric D. Helms
Red Hat Engineering
Ph.D. Student - North Carolina State University

–
You received this message because you are subscribed to the Google
Groups “foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send
an email to foreman-dev+unsubscribe@googlegroups.com
mailto:foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

15

I have tried the wiki + mailing list approach with facets, and it didn't
work too well.

Pain point that I experienced:

  1. Mail discussions were quickly split into separate subjects, so it became
    pretty impossible to track multiple threads inside it.
  2. There was no single point of truth that everyone could see the whole
    picture at once.

From the other hand, how do we track iterations (maybe it's a noob
question…)?
Let's say I write a proposal, it gets reviewed and people comment on it.
Now I want to address some of those comments.
If I add a new commit, will other comments remain visible? I am concerned
that they will become "comments on outdated diff" and loose their
visibility because some syntactical rewording.

Another concern:
What about design drift? Especially with complex features, the design
usually drifts from what is written when the implementation phase begins.

In general I agree with Eric - if we won't try new things, we won't be able
to evolve our processes to something better.

Shim

··· On Wednesday, April 13, 2016 at 6:41:29 PM UTC+3, jsherril wrote: > > On 04/13/2016 11:37 AM, Eric D Helms wrote: > > > > > > On Wed, Apr 13, 2016 at 10:37 AM, Tomas Strachota > > <mailto:tstra...@redhat.com >> wrote: > > > > On 04/13/2016 11:50 AM, Lukas Zapletal wrote: > > > > (TL;DR: Is [0] a good idea?) > > > > > > I would like to mention first, that we already *have* such a > > thing. It > > is my attempt to do the very same, inspired by oVirt team. They > > maintain > > Wiki which seems to be quite appropriate for this purpose (quick > > edits, > > good formatting), and we have it here: > > > > http://projects.theforeman.org/projects/foreman/wiki/Features > > > > Unfortunately, I did not find a way how to create a list of > > sub-pages on > > a RedMine wiki page, so it's not that transparent. An example > > entry is > > here: > > > > > http://projects.theforeman.org/projects/foreman/wiki/CentralizedLogging > > > > To the date, we have six feature designs on the wiki. The lack > > of the > > index page is perhaps the reason why this failed. It definitely > > needs > > more transparency. > > > > I am not against the new RFC repo, in case plugins are allowed > > to use > > it. Creating RFC repos for each plugin or component would make > > things > > actually worse. But I share skepticism here, I am not sure if it > > helps > > to improve things. I already sent two reminders to the list > about > > putting new features on our Wiki. > > > > If we are able to do the same, but on our Wiki, I lean towards > this > > because to me it's more convenient way of editing the stuff. > > > > > > +1 for giving a RFC github repo a try. I believe that github has > > bigger chances to be adopted. People use it daily and the UI is very > > clean to comment and review the changes too. > > > > > > > > For me, as Tomas says, the key here is "giving...a try". We have a few > > tools, and a few methods at our disposal that have largely been tried > > for managing large features or discussions. And yet, we go round and > > round because, as Greg points out, the real problem is not being solved > > with respect to designs. I believe it behooves us to try something else. > > If it fails, at least we experimented, gave it a shot and we try > > something else to find what works for us. If it works, then bravo. There > > is no silver bullet, but the trick is trying something until we find > > what works by and large. > > > > Apologies if I am restating what has already been said, but the > > questions I have seen plague us are: > > > > a) How to present a design with text, images, presentations, media, > links? > > b) How to solicit feedback on a design document? > > c) How, as someone reviewing a design, do I give feedback? > > > > The key, to me, is the last question because that is how designs get > > better and help you to avoid finding issues further into the process > > where the cost increases ten-fold with each step. Let's walk through > > some example workflows using our tools. > > > > Wiki: > > > > 1) Create wiki page > > 2) Add text, sections, links, media, images, etc. > > 3) Send email to list announcing design > > 4) Users and devs go to Redmine and post comments? Do they reply to the > > email thread? How do they reference pieces of the design? > > 5) Comments iterated on > > 6) Email sent saying hey design got updated > > 7) Rinse and repeat 4-7 > > > > Email: > > > > 1) Write up design within the confines of an email with text and > > links, find somewhere to host images or media to reference > > 2) Send email to users? to dev? to both? cross-post? > > 3) Users and devs reply to email, inline comments allow commenting on > > specific sections > > 4) At some point, comments are waded through and a new email is sent > > with updated design > > 5) Rinse and repeat > > > > GIthub RFC > > > > 1) Write up document with text, sections, links, media, references, > images > > 2) Open PR to RFC repo > > 3) Send email noting a new design is ready for comment > > 4) Users and devs go to PR and post comments directly to design > > 5) Design is iterated on and new version is pushed to the PR > > 6) Email sent noting updated design > > > > > > Wiki and email suffer from a common flaw -- how do I see what parts of > > the design were updated between iterations easily so I can focus on the > > parts I care about? For me, that is the nice part of the RFC repository, > > we take the same workflow we use for code and apply it to designs. > > I would also add that email has the drawback in that the discussion can > get very very large very quickly and its hard to see where things landed > and for discussions to get out off topic or into crazy ideas that may > never happen. > > -Justin > > > > > > > Eric > > > > > > > > I'm also for using one repo for the core and plugins. Bigger changes > > affect multiple areas which will be easier to track at one place. > > > > T. > > > > > > -- > > You received this message because you are subscribed to the Google > > Groups "foreman-dev" group. > > To unsubscribe from this group and stop receiving emails from it, > > send an email to foreman-dev...@googlegroups.com > > <mailto:foreman-dev%2Bunsubscribe@googlegroups.com >. > > For more options, visit https://groups.google.com/d/optout. > > > > > > > > > > -- > > Eric D. Helms > > Red Hat Engineering > > Ph.D. Student - North Carolina State University > > > > -- > > You received this message because you are subscribed to the Google > > Groups "foreman-dev" group. > > To unsubscribe from this group and stop receiving emails from it, send > > an email to foreman-dev...@googlegroups.com > > <mailto:foreman-dev+unsubscribe@googlegroups.com >. > > For more options, visit https://groups.google.com/d/optout. > >
16

Dominic, this is a very good point, of which I kinda tend to agree. But I also might offer a counterpoint that warrants some thought.

It is true that we already have plenty of tools at our disposal that aren't being used to their full potential, or "properly" as you put it, some that probably could even already solve what we're discussing. It's also possible that these current tools aren't being used because they don't fit the team and/or the particular environment. (a) They don't really fit in the current workflow, or (b) it's another tool that I have to sign into could be some possible reasons they aren't being used. Maybe it's as simple as, "I'm always thinking in git and markdown these days."

Instead of immediately investigating new tools, let's spend some time examining our currently available tools that people obviously put time into making available, and figure out what shortcomings or dislikes the team may have, if there are any. Maybe it's as simple as finding better visibility for what we already have. But I wouldn't rule out switching to a new tool either simply because we already have a thing that solves a problem.

TL;DR - let's examine/discuss our current tools with their pros/cons/likes/dislikes to give us a better idea of what we might want out of something new if we reach the decision of switching to something new.

··· ----- Original Message ----- > On 12/04/16 15:11, Ohad Levy wrote: > > > > > > On Tue, Apr 12, 2016 at 5:02 PM, Dominic Cleal > > wrote: > > > > On 12/04/16 14:27, Greg Sutcliffe wrote: > > > Hi all, > > > > > > (TL;DR: Is [0] a good idea?) > > > > > > For a while now, I've been thinking about the issue of open design > > > process, > > > and how we can take the design discussion forward (Dominic sent me > > > this > > > excellent post[1] on the subject a while back - thanks!). > > > > To be clear to my position, I was only linking to the page - I don't > > think I'm in favour of adding such a process to Foreman. > > > > > > can you elaborate more on why? > > We've got plenty of tools (this mailing list, tickets, a wiki) that > aren't being used properly without adding another tool and process. I > don't think adding another method is necessary to create more content or > discussion about a change. > > -- > Dominic Cleal > dominic@cleal.org

–

  • adam price
17

> In general I agree with Eric - if we won't try new things, we won't be able
> to evolve our processes to something better.

I agree.

Let's start with Wiki first :slight_smile:

··· -- Later, Lukas #lzap Zapletal
18

A few people to reply to here, sorry for the length :stuck_out_tongue:

> We've got plenty of tools (this mailing list, tickets, a wiki) that
> aren't being used properly without adding another tool and process. I
> don't think adding another method is necessary to create more content or
> discussion about a change.

I would argue that we're not adding a new tool (we already use GitHub) and
that
we do need to designate an area where discussion should be collected. Eric
adds
some good thoughts in his reply which are also relevant here.

> I would like to mention first, that we already have such a thing. It
> is my attempt to do the very same, inspired by oVirt team. They maintain
> Wiki which seems to be quite appropriate for this purpose (quick edits,
> good formatting), and we have it here:

I'll snip here, but I think you've already listed most of the issues with
the
wiki. I'll add that maintaing the list of proposals is trickier (for GH it's
just the open pull requests). Also, history viewing isn't as good, and
there's
not a clear distinction of comments vs changes to the RFC text itself. Also,
the fact that you already created it and it isn't used says a lot about that
experiment :slight_smile:

While I believe the wiki could work, I think Git handles this better.

> If we are able to do the same, but on our Wiki, I lean towards this
> because to me it's more convenient way of editing the stuff.

GitHub's UI allows for in-page editing if you don't want to clone the repo
locally. This is pretty equivalent to Wiki editing in my view.

> What I like about github is that the RFC would, I assume, be a PR until
> interested parties could ack it (or majority acked it, or whatever
groundrules
> are established). As a PR comments would be at contextual locations in the
> document so conversations could happen in-place.

This is also my view. GitHub gives both contextual discussion and easy
history
overview. A wiki can do this, but the viewing of such data isn't as clean.

> TL;DR - let's examine/discuss our current tools with their
> pros/cons/likes/dislikes to give us a better idea of what we might want
out of
> something new if we reach the decision of switching to something new.

As per earlier in this reply - GitHub isn't a new tool, we already use it
extensively. This is just an attempt to put some minimal structure to help
us
use the tools better for this purpose :wink:

> …

Not much for me to reply to here, we seem to agree entirely. Thanks for
expanding on some of the things I didn't say though :slight_smile:

> 1. Mail discussions were quickly split into separate subjects, so it
became
> pretty impossible to track multiple threads inside it.
> 2. There was no single point of truth that everyone could see the whole
picture at once.

> From the other hand, how do we track iterations?
> Let's say I write a proposal, it gets reviewed and people comment on it.
> Now I want to address some of those comments.
> If I add a new commit, will other comments remain visible? I am concerned
> that they will become "comments on outdated diff" and loose their
visibility
> because some syntactical rewording.

Some good points here. Tracking iterations, I think, is simply a case of
sequential commits. The PR will, of course, show the "latest iteration" of
the
RFC, but for those wishing to read previous version, those commits are
there.
In-line comments will indeed be hidden by the outdated diff, but (a) they
are
only hidden when that line changes, not the whole file, and (b) we should
keep major discussion in the global PR discussion, rather than in-line
comments. Should a valid inline comment get accidentally hidden, it's
acceptable, I think, to copy that comment to the main thread to keep it
visible.

> Another concern: What about design drift? Especially with complex
features,
> the design usually drifts from what is written when the implementation
phase
> begins.

In the sample repo, I cover this under The RFC
Lifecycle,
last paragraph. Specifically, it states that modifications to active RFCs
are
permitted via a new PR.

What's key here is that we don't squash commits in this repo, so the history
for a given RFC file is always available, right back to iteration 1. With a
rebase
as well, then all the iteration commits (at the time of the merge) will be
grouped
together in the git log.

> In general I agree with Eric - if we won't try new things, we won't be
able
to evolve our processes to something better.

Indeed, we don't have to get this perfect on take 1 - PRs to the process
README
are entirely acceptable :stuck_out_tongue:

> Let's start with Wiki first :slight_smile:

Looking at the replies so far, I don't think you're winning the wiki
argument :stuck_out_tongue:

Good feedback so far guys, thanks!
Greg

··· On 13 April 2016 at 09:07, Dominic Cleal wrote: On 13 April 2016 at 10:50, Lukas Zapletal wrote: On 13 April 2016 at 12:01, Tom McKay wrote: On 13 April 2016 at 16:12, Adam Price wrote: On 13 April 2016 at 16:37, Eric D Helms wrote: On 14 April 2016 at 09:33, wrote: On 14 April 2016 at 10:18, Lukas Zapletal wrote:

On 14 April 2016 at 10:18, Lukas Zapletal lzap@redhat.com wrote:

In general I agree with Eric - if we won’t try new things, we won’t be
able
to evolve our processes to something better.

I agree.

Let’s start with Wiki first :slight_smile:

–
Later,
Lukas #lzap Zapletal

–
You received this message because you are subscribed to the Google Groups
“foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

–
Greg
IRC: gwmngilfen

19

> > In general I agree with Eric - if we won't try new things, we won't be
> able
> > to evolve our processes to something better.
>
> I agree.
>
> Let's start with Wiki first :slight_smile:
>

Been there and no, (Redmine) wik really isn't good tool for this. Let me
share some experience with remote execution design,
as I think we had pretty realistic demands on tooling that would support
putting together designs, collaboration and
review.

We started with wiki (to try to use existing tooling before using something
more fancy), but we switched to Redmine issue
[2] pretty soon, as there is little added value in pure wiki vs. issue
description, and
the issue has more useful metadata there. But we hit need for recording
design images: we used plantuml,
as it worked best for capturing the our thoughts and trying to use that
with uploading design images to the wiki/issue felt just
bad.

What we did then was creating a git repo with basic jekyll structure [3],
which is basically RFC - kind of repo.
The Jekyll was really good fit, as we had pretty nicely formatted document,
and with plantuml plugin, we could
track the design images in source code, while jekyll doing the rendering
for us. I've probably seen the
output of the design [4].

We did not use the review process via github while working on the design,
as most of the work was done while we were
sitting together in a room. But the repo was open for PRs from the
beginning, if anyone wanted to jump in.

I'm still using the pages every now and then, when I need to explain some
of our decisions and motivations to somebody.

Long story short: for remote execution work, a git repo with jekyll
structure and plantuml was perfect fit and I based on the experience,
I can just recommend using this in the RFC repo as well.

[1] -
http://projects.theforeman.org/projects/foreman/wiki/Remote_Execution_Design
[2] - Feature #9893: Remote Execution Design - Foreman Remote Execution - Foreman
[3] - GitHub - iNecas/foreman-rex: Repository for collecting and sharing work done as part of http://projects.theforeman.org/issues/9893: Foreman Remote Execution design
[4] - :: Foreman Remote Execution

– Ivan

··· On Thu, Apr 14, 2016 at 11:18 AM, Lukas Zapletal wrote:

–
Later,
Lukas #lzap Zapletal

–
You received this message because you are subscribed to the Google Groups
“foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

20

I think this problem is there with our current PR reviews already and
people learned to live
with this.

··· On Thu, Apr 14, 2016 at 11:51 AM, Greg Sutcliffe wrote:

On 14 April 2016 at 09:33, sshtein@redhat.com wrote:

  1. Mail discussions were quickly split into separate subjects, so it
    became
    pretty impossible to track multiple threads inside it.
  2. There was no single point of truth that everyone could see the whole
    picture at once.

From the other hand, how do we track iterations?
Let’s say I write a proposal, it gets reviewed and people comment on it.
Now I want to address some of those comments.
If I add a new commit, will other comments remain visible? I am concerned
that they will become “comments on outdated diff” and loose their
visibility
because some syntactical rewording.

Some good points here. Tracking iterations, I think, is simply a case of
sequential commits. The PR will, of course, show the “latest iteration” of
the
RFC, but for those wishing to read previous version, those commits are
there.
In-line comments will indeed be hidden by the outdated diff, but (a) they
are
only hidden when that line changes, not the whole file, and (b) we should
keep major discussion in the global PR discussion, rather than in-line
comments. Should a valid inline comment get accidentally hidden, it’s
acceptable, I think, to copy that comment to the main thread to keep it
visible.