[PROPOSAL] Collaboration on NuttX Workflow

[Anthony Merlino <an...@vergeaero.com>]

Hi all,

I would like to propose a method of collaboration for the workflow
requirements. Nathan and Brennan have done some legwork that is now on the
Wiki - which is a great starting point. Unfortunately, it hasn't seen much
collaboration other than a few comments.

I believe part of the issue here is that no one wants to go in and change
someone else's proposal. The wiki is also not the most friendly to use for
collaboration and has no method of tracking changes (at least to my
knowledge).

I have started a CONTRIBUTORS.md file in a personal fork of incubator-nuttx:

https://github.com/antmerlino/incubator-nuttx/blob/antmerlino-contributors-md/CONTRIBUTORS.md

For those not familiar, CONTRIBUTORS.md is a common file found in many
other open source projects that tells interested parties how to contribute
to the project. It is essentially the workflow document.

I have asked David to show me the ropes of suggesting changes in the Github
UI. The suggested changes land as separate commits, which allows us to
track changes and authorship while developing this document. You can also
pull the repo, make changes, and open a PR against the branch too, if you
don't want to work in Github. Of course we can squash it all together at
the end when/if we merge it in. This is a much more collaborative way of
working. We can make comments in context, see what others are suggesting,
and integrate that feedback quickly into the deliverable.  Otherwise we are
waiting for some poor soul to do 90% of the work themselves and then do the
extra 10% work of integrating people's feedback from the emails. That's not
a good collaboration method.

If others are keen on this idea, I propose that we move this branch and PR
from my personal fork, to the incubator-nuttx repository, collaborate on
the PR, and land when we are all happy. Based on the discussion here, I
will call a vote to move the PR and branch.

Best,
Anthony

Re: [PROPOSAL] Collaboration on NuttX Workflow

[Nathan Hartman <ha...@gmail.com>]

On Thu, Dec 26, 2019 at 9:51 AM Anthony Merlino <an...@vergeaero.com> wrote:
> I have started a CONTRIBUTORS.md file in a personal fork of incubator-nuttx:
>
> https://github.com/antmerlino/incubator-nuttx/blob/antmerlino-contributors-md/CONTRIBUTORS.md
>
> For those not familiar, CONTRIBUTORS.md is a common file found in many
> other open source projects that tells interested parties how to contribute
> to the project. It is essentially the workflow document.
>
> I have asked David to show me the ropes of suggesting changes in the Github
> UI. The suggested changes land as separate commits, which allows us to
> track changes and authorship while developing this document. You can also
> pull the repo, make changes, and open a PR against the branch too, if you
> don't want to work in Github. Of course we can squash it all together at
> the end when/if we merge it in. This is a much more collaborative way of
> working. We can make comments in context, see what others are suggesting,
> and integrate that feedback quickly into the deliverable.  Otherwise we are
> waiting for some poor soul to do 90% of the work themselves and then do the
> extra 10% work of integrating people's feedback from the emails. That's not
> a good collaboration method.
>
> If others are keen on this idea, I propose that we move this branch and PR
> from my personal fork, to the incubator-nuttx repository, collaborate on
> the PR, and land when we are all happy. Based on the discussion here, I
> will call a vote to move the PR and branch.

Hello Anthony,

Thank you for taking initiative here. I like the idea of a CONTRIBUTORS.md file.

Here is a great opportunity for our fledgling Apache NuttX Podling to
practice working together: I suggest to put CONTRIBUTORS.md into the
official Apache NuttX repo right now. Let's move the text that is in
the Confluence workflow proposal right now and put it into
CONTRIBUTORS.md. Already some work was done so let's not throw it
away.

Once it is in CONTRIBUTORS.md, anyone can make a git clone, add/edit
some text to CONTRIBUTORS.md, and send a patch or a pull request. The
community will discuss/review it. If there is consensus that the text
is a good addition to CONTRIBUTORS.md, a committer will commit it and
we will proceed from there.

Advantages:

(1) We will practice our workflow while we write it.

(2) It will be The Apache Way.

Nathan

Re: [PROPOSAL] Collaboration on NuttX Workflow

[Brennan Ashton <ba...@brennanashton.com>]

For what it is worth that is no longer my proposal which is fine (someone
should likely drop my name from the title). Also the last few days have
been holiday time for many people. I for instance left my laptop at home,
and editing docs on a phone did not seem like a great use of time.

With confluence you can comment easily on specific lines, just highlight it
and you will see the comment option. As I mentioned in the confluence page
once it stabilizes it should probably move to the contributing.md file.

It would be nice if there was a single place or at least platform  we did
this work on, but long as it is public I guess I don't care too much.

--Brennan

On Thu, Dec 26, 2019, 6:51 AM Anthony Merlino <an...@vergeaero.com> wrote:

> Hi all,
>
> I would like to propose a method of collaboration for the workflow
> requirements. Nathan and Brennan have done some legwork that is now on the
> Wiki - which is a great starting point. Unfortunately, it hasn't seen much
> collaboration other than a few comments.
>
> I believe part of the issue here is that no one wants to go in and change
> someone else's proposal. The wiki is also not the most friendly to use for
> collaboration and has no method of tracking changes (at least to my
> knowledge).
>
> I have started a CONTRIBUTORS.md file in a personal fork of
> incubator-nuttx:
>
>
> https://github.com/antmerlino/incubator-nuttx/blob/antmerlino-contributors-md/CONTRIBUTORS.md
>
> For those not familiar, CONTRIBUTORS.md is a common file found in many
> other open source projects that tells interested parties how to contribute
> to the project. It is essentially the workflow document.
>
> I have asked David to show me the ropes of suggesting changes in the Github
> UI. The suggested changes land as separate commits, which allows us to
> track changes and authorship while developing this document. You can also
> pull the repo, make changes, and open a PR against the branch too, if you
> don't want to work in Github. Of course we can squash it all together at
> the end when/if we merge it in. This is a much more collaborative way of
> working. We can make comments in context, see what others are suggesting,
> and integrate that feedback quickly into the deliverable.  Otherwise we are
> waiting for some poor soul to do 90% of the work themselves and then do the
> extra 10% work of integrating people's feedback from the emails. That's not
> a good collaboration method.
>
> If others are keen on this idea, I propose that we move this branch and PR
> from my personal fork, to the incubator-nuttx repository, collaborate on
> the PR, and land when we are all happy. Based on the discussion here, I
> will call a vote to move the PR and branch.
>
> Best,
> Anthony
>

Re: [PROPOSAL] Collaboration on NuttX Workflow

[Gregory Nutt <sp...@gmail.com>]

Things are stalled no because of the Holidays.  You are looking at only 
about 2-3 days of of 1-hour per day effort.  It wouldn't hurt to wait 
for a few days when people are better able to contribute.

Brennan and Nathan have been the sole "authors" of the document.  I have 
not been directly contributing because I wanted to avoid the "too many 
chefs" problem.  So I have only been adding suggested content as 
comments that can be addresses, or not, depending on the intent of the 
authors.

Hopefully, if enough enough eyes and brains work the document we will 
have assured PPMC agreement.

Greg

On 12/26/2019 8:51 AM, Anthony Merlino wrote:
> Hi all,
>
> I would like to propose a method of collaboration for the workflow
> requirements. Nathan and Brennan have done some legwork that is now on the
> Wiki - which is a great starting point. Unfortunately, it hasn't seen much
> collaboration other than a few comments.
>
> I believe part of the issue here is that no one wants to go in and change
> someone else's proposal. The wiki is also not the most friendly to use for
> collaboration and has no method of tracking changes (at least to my
> knowledge).
>
> I have started a CONTRIBUTORS.md file in a personal fork of incubator-nuttx:
>
> https://github.com/antmerlino/incubator-nuttx/blob/antmerlino-contributors-md/CONTRIBUTORS.md
>
> For those not familiar, CONTRIBUTORS.md is a common file found in many
> other open source projects that tells interested parties how to contribute
> to the project. It is essentially the workflow document.
>
> I have asked David to show me the ropes of suggesting changes in the Github
> UI. The suggested changes land as separate commits, which allows us to
> track changes and authorship while developing this document. You can also
> pull the repo, make changes, and open a PR against the branch too, if you
> don't want to work in Github. Of course we can squash it all together at
> the end when/if we merge it in. This is a much more collaborative way of
> working. We can make comments in context, see what others are suggesting,
> and integrate that feedback quickly into the deliverable.  Otherwise we are
> waiting for some poor soul to do 90% of the work themselves and then do the
> extra 10% work of integrating people's feedback from the emails. That's not
> a good collaboration method.
>
> If others are keen on this idea, I propose that we move this branch and PR
> from my personal fork, to the incubator-nuttx repository, collaborate on
> the PR, and land when we are all happy. Based on the discussion here, I
> will call a vote to move the PR and branch.
>
> Best,
> Anthony
>

Re: [PROPOSAL] Collaboration on NuttX Workflow

[Gregory Nutt <sp...@gmail.com>]

> +1 Give it a go
> +1 move it
There is no reason to rush.

RE: [PROPOSAL] Collaboration on NuttX Workflow

[David Sidrane <Da...@nscdg.com>]

+1 Give it a go
+1 move it

-----Original Message-----
From: Anthony Merlino [mailto:anthony@vergeaero.com]
Sent: Thursday, December 26, 2019 6:52 AM
To: dev@nuttx.apache.org
Subject: [PROPOSAL] Collaboration on NuttX Workflow

Hi all,

I would like to propose a method of collaboration for the workflow
requirements. Nathan and Brennan have done some legwork that is now on the
Wiki - which is a great starting point. Unfortunately, it hasn't seen much
collaboration other than a few comments.

I believe part of the issue here is that no one wants to go in and change
someone else's proposal. The wiki is also not the most friendly to use for
collaboration and has no method of tracking changes (at least to my
knowledge).

I have started a CONTRIBUTORS.md file in a personal fork of incubator-nuttx:

https://github.com/antmerlino/incubator-nuttx/blob/antmerlino-contributors-md/CONTRIBUTORS.md

For those not familiar, CONTRIBUTORS.md is a common file found in many
other open source projects that tells interested parties how to contribute
to the project. It is essentially the workflow document.

I have asked David to show me the ropes of suggesting changes in the Github
UI. The suggested changes land as separate commits, which allows us to
track changes and authorship while developing this document. You can also
pull the repo, make changes, and open a PR against the branch too, if you
don't want to work in Github. Of course we can squash it all together at
the end when/if we merge it in. This is a much more collaborative way of
working. We can make comments in context, see what others are suggesting,
and integrate that feedback quickly into the deliverable.  Otherwise we are
waiting for some poor soul to do 90% of the work themselves and then do the
extra 10% work of integrating people's feedback from the emails. That's not
a good collaboration method.

If others are keen on this idea, I propose that we move this branch and PR
from my personal fork, to the incubator-nuttx repository, collaborate on
the PR, and land when we are all happy. Based on the discussion here, I
will call a vote to move the PR and branch.

Best,
Anthony

Re: [PROPOSAL] Collaboration on NuttX Workflow

[Justin Mclean <ju...@classsoftware.com>]

Hi,

> The wiki is also not the most friendly to use for
> collaboration and has no method of tracking changes (at least to my
> knowledge).

It tracks changes and you can revert to a previous version, so there’s no issues there.

>  Of course we can squash it all together at the end when/if we merge it in.

Why? Authorship information is then lost.

> This is a much more collaborative way of
> working. We can make comments in context, see what others are suggesting,
> and integrate that feedback quickly

Which you can do in the wiki as well.

We can also grant edit access to non committers in the Wiki.

> I will call a vote to move the PR and branch.

Please discuss and reach consensus before calling a vote, and for something like this why would you need a vote?

Thanks,
Justin

Re: [PROPOSAL] Collaboration on NuttX Workflow

[Nathan Hartman <ha...@gmail.com>]

On Thu, Dec 26, 2019 at 12:43 PM Gregory Nutt <sp...@gmail.com> wrote:

>
> > I would like to propose a method of collaboration for the workflow
> > requirements. Nathan and Brennan have done some legwork that is now on
> the
> > Wiki - which is a great starting point. Unfortunately, it hasn't seen
> much
> > collaboration other than a few comments.
>
> Probably more than a few.  A lot of the important meat of the workflow
> is in comments, pending incorporation as text.  I think we cannot lose
> that.  Will be these be brought into the GIT somehow?  Or should should
> we, perhaps just append all of the comments at the end of the page as
> "Notes" for subsequent integration.


The comments must be saved!

We could, at the very least, copy the text of each comment and paste it
into the appropriate section. Even though the result will be ugly at first,
it can be edited later to fix it.

Nathan

Re: [PROPOSAL] Collaboration on NuttX Workflow

[Gregory Nutt <sp...@gmail.com>]

> I would like to propose a method of collaboration for the workflow
> requirements. Nathan and Brennan have done some legwork that is now on the
> Wiki - which is a great starting point. Unfortunately, it hasn't seen much
> collaboration other than a few comments.

Probably more than a few.  A lot of the important meat of the workflow 
is in comments, pending incorporation as text.  I think we cannot lose 
that.  Will be these be brought into the GIT somehow?  Or should should 
we, perhaps just append all of the comments at the end of the page as 
"Notes" for subsequent integration.