You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@nuttx.apache.org by David Sidrane <da...@apache.org> on 2019/12/21 07:22:43 UTC
[CALL for TOP Down workflow Requirements]
All,
Please help flesh this out.
Proposed Workflow Requirements (REQ) and Derived Requirements (DREQ)
REQ1) master is branches of apps and nuttx have to always build
REQ1.1) ALL development work is done on branches.
DREQ1.1.1) master is branch protected prevention pushes to it.
REQ2) git bisect shall always be able to build master of the project at every commit.
DREQ2.a) merges to master may use squash commits from a PR when atomic commits are needed to insure REC2.
DREQ2.b) merges to master may use rebase commits from a PR when NON atomic commits will for insure REC2.
REQ3) Submissions shall be PRs against branches typically master. But PR shall be accepted against other branches.
(i.e netlink_crypto)
REQ3.1) naming conventions shall reflect lineage:
REQ3.1.a) naming conventions of branches shall be in the form <root>_<activity>
master_pr-add_imxrt20, netlink_crypto-pr-bugfix_AES
REQ3.1.b) submissions affecting multiple repos shall use the same branches name on all repos.
DREQ3.1.b.1) CI shall test multiple repos by branch name
REQ4) committer may collaborate on branches.
REC5) While PR's are preferred, patches may be accepted.
DREC5.1) Committers receiving patches shall apply them to a new branch (per REQ3) and open a PR.
REC5.1) Committers shall attribute work to the person submitting patch
REC6) All PR requires a review.
DREC6.1) the project shall publish a list of subject experts
REC6.1) Request for review shall be made via email to subject experts or PPMC.
REC6.1.1) Multiple reviewers shall be required on OS internals.
REC6.1.2) Multiple reviewers may be required on NON OS internals.
David
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
David, Brennan,
Thanks for starting this David, I think you are the only person that
could have gotten us out of the run we are in.
We need to get this into a place where we can collaborate on it.
Brennan, Justin suggested that we use Confluence for document
collaboration. We have no other way to collaborate and we will
eventually need a home for project-related materials, separate from the
user-oriented Wiki. What do you think? David was initially very
opposed to this. Do you see any other alternatives under the Apache
framework?
Some general comments.
* This fragment of requirements primarily addresses general rules and
philosophy. It is shy on any actual work follow. Today I will
scrounge through the dev list and see if I can cull other attempts
at defining the workflow.
* The think that REQ and DREQ formalisms are unnecessary. I has seen
such notation used to specify the unit-under-test before, but I
don't think is is needed here (this is not specifying a
unit-under-test). Remove these will greatly improve readability.
More to come,
Greg
On 12/21/2019 1:22 AM, David Sidrane wrote:
> All,
>
> Please help flesh this out.
>
> Proposed Workflow Requirements (REQ) and Derived Requirements (DREQ)
>
> REQ1) master is branches of apps and nuttx have to always build
> REQ1.1) ALL development work is done on branches.
> DREQ1.1.1) master is branch protected prevention pushes to it.
>
> REQ2) git bisect shall always be able to build master of the project at every commit.
> DREQ2.a) merges to master may use squash commits from a PR when atomic commits are needed to insure REC2.
> DREQ2.b) merges to master may use rebase commits from a PR when NON atomic commits will for insure REC2.
>
> REQ3) Submissions shall be PRs against branches typically master. But PR shall be accepted against other branches.
> (i.e netlink_crypto)
> REQ3.1) naming conventions shall reflect lineage:
> REQ3.1.a) naming conventions of branches shall be in the form <root>_<activity>
> master_pr-add_imxrt20, netlink_crypto-pr-bugfix_AES
> REQ3.1.b) submissions affecting multiple repos shall use the same branches name on all repos.
> DREQ3.1.b.1) CI shall test multiple repos by branch name
>
> REQ4) committer may collaborate on branches.
>
> REC5) While PR's are preferred, patches may be accepted.
> DREC5.1) Committers receiving patches shall apply them to a new branch (per REQ3) and open a PR.
> REC5.1) Committers shall attribute work to the person submitting patch
>
> REC6) All PR requires a review.
> DREC6.1) the project shall publish a list of subject experts
> REC6.1) Request for review shall be made via email to subject experts or PPMC.
> REC6.1.1) Multiple reviewers shall be required on OS internals.
> REC6.1.2) Multiple reviewers may be required on NON OS internals.
>
>
> David
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> Also one would like that the code to be tested (also hacktesting) through something like SonarCube.
Apache provides SonarCube support for projects
Thanks,
Justin
Re: [CALL for TOP Down workflow Requirements]
Posted by Brennan Ashton <ba...@brennanashton.com>.
On Sat, Dec 21, 2019, 12:40 AM Disruptive Solutions <
disruptivesolutionsnl@gmail.com> wrote:
> You would like te see some REQuirements would be addressed by some DevOps
> thoughts.. but C/C++ are still challenging here. And then the principle:
> automate where you can!
>
> (
> https://www.google.nl/amp/s/devops.com/devops-challenges-c-c-projects/amp/
> )
>
You found my company's marketing material. Conan is not likely helpful
here since we are not creating a bunch of component packages.
Putting on my devops hat. Start simple or you will through good intentions
mess no one will use. Then when you have your pains showing look for
existing tools because they usually exist.
--Brennan
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Disruptive Solutions <di...@gmail.com>.
You would like te see some REQuirements would be addressed by some DevOps thoughts.. but C/C++ are still challenging here. And then the principle: automate where you can!
( https://www.google.nl/amp/s/devops.com/devops-challenges-c-c-projects/amp/)
Also one would like that the code to be tested (also hacktesting) through something like SonarCube.
Release gates, Ring based deployments, DTAP, Feature Flags, etc... all ideas to use or to look at? Nuttx in the Cloud?
Ben
Verstuurd vanaf mijn iPhone
> Op 21 dec. 2019 om 08:56 heeft Brennan Ashton <ba...@brennanashton.com> het volgende geschreven:
>
> On Fri, Dec 20, 2019, 11:22 PM David Sidrane <da...@apache.org> wrote:
>
>> All,
>>
>> Please help flesh this out.
>>
>> Proposed Workflow Requirements (REQ) and Derived Requirements (DREQ)
>>
>> REQ1) master is branches of apps and nuttx have to always build
>> REQ1.1) ALL development work is done on branches.
>> DREQ1.1.1) master is branch protected prevention pushes to it.
>>
>> REQ2) git bisect shall always be able to build master of the project at
>> every commit.
>> DREQ2.a) merges to master may use squash commits from a PR when
>> atomic commits are needed to insure REC2.
>> DREQ2.b) merges to master may use rebase commits from a PR when NON
>> atomic commits will for insure REC2.
>>
>> REQ3) Submissions shall be PRs against branches typically master. But PR
>> shall be accepted against other branches.
>> (i.e netlink_crypto)
>> REQ3.1) naming conventions shall reflect lineage:
>> REQ3.1.a) naming conventions of branches shall be in the form
>> <root>_<activity>
>> master_pr-add_imxrt20, netlink_crypto-pr-bugfix_AES
>> REQ3.1.b) submissions affecting multiple repos shall use the same
>> branches name on all repos.
>> DREQ3.1.b.1) CI shall test multiple repos by branch name
>>
>
> I would like to loosen up the branch naming requirements, it will make it
> harder for people to contribute little things coming from the "GitHub"
> world, it's not something I see too much outside of the workplace. Also the
> generated branches on GitHub from a PR are using the ids. I'm not trying
> to bring tooling in, but I think we should be aware of this and I think it
> brings minimal gain. I would be more in favor of the title or body of a PR
> doing the linking if we really need the standard to link things together.
> We need to be very sensitive to increases in complexity or we will loose
> new contributors.
>
>
>
>>
>> REQ4) committer may collaborate on branches.
>>
>> REC5) While PR's are preferred, patches may be accepted.
>> DREC5.1) Committers receiving patches shall apply them to a new branch
>> (per REQ3) and open a PR.
>> REC5.1) Committers shall attribute work to the person submitting patch
>>
>> REC6) All PR requires a review.
>> DREC6.1) the project shall publish a list of subject experts
>> REC6.1) Request for review shall be made via email to subject experts or
>> PPMC.
>> REC6.1.1) Multiple reviewers shall be required on OS internals.
>> REC6.1.2) Multiple reviewers may be required on NON OS internals.
>>
>>
>> David
>
>
> The rest sounds good. I would say let's start minimal and work up if we
> find quality or complexity issues.
>
> --Brennan
Re: [CALL for TOP Down workflow Requirements]
Posted by Brennan Ashton <ba...@brennanashton.com>.
We can still use GitHub functionality for handling merges etc.. at the end
of the day my understanding is the code just has to end up in the repos and
synced to Apache's severs.
Not asking to add anything to the proposal just STRIKE REQ3.1
On Sat, Dec 21, 2019, 12:47 AM David Sidrane <da...@apache.org> wrote:
> Hi Brennan,
>
> I agree with your reasoning and welcome the change, but let me expand on
> the initial reasoning. below.
>
> On 2019/12/21 07:56:35, Brennan Ashton <ba...@brennanashton.com> wrote:
> > On Fri, Dec 20, 2019, 11:22 PM David Sidrane <da...@apache.org> wrote:
> >
> > > All,
> > >
> > > Please help flesh this out.
> > >
> > > Proposed Workflow Requirements (REQ) and Derived Requirements (DREQ)
> > >
> > > REQ1) master is branches of apps and nuttx have to always build
> > > REQ1.1) ALL development work is done on branches.
> > > DREQ1.1.1) master is branch protected prevention pushes to it.
> > >
> > > REQ2) git bisect shall always be able to build master of the project at
> > > every commit.
> > > DREQ2.a) merges to master may use squash commits from a PR when
> > > atomic commits are needed to insure REC2.
> > > DREQ2.b) merges to master may use rebase commits from a PR when
> NON
> > > atomic commits will for insure REC2.
> > >
> > > REQ3) Submissions shall be PRs against branches typically master. But
> PR
> > > shall be accepted against other branches.
> > > (i.e netlink_crypto)
> > > REQ3.1) naming conventions shall reflect lineage:
> > > REQ3.1.a) naming conventions of branches shall be in the form
> > > <root>_<activity>
> > > master_pr-add_imxrt20,
> netlink_crypto-pr-bugfix_AES
> > > REQ3.1.b) submissions affecting multiple repos shall use the same
> > > branches name on all repos.
> > > DREQ3.1.b.1) CI shall test multiple repos by branch name
> > >
> >
> > I would like to loosen up the branch naming requirements, it will make it
> > harder for people to contribute little things coming from the "GitHub"
> > world, it's not something I see too much outside of the workplace. Also
> the
> > generated branches on GitHub from a PR are using the ids. I'm not trying
> > to bring tooling in, but I think we should be aware of this and I think
> it
> > brings minimal gain. I would be more in favor of the title or body of a
> PR
> > doing the linking if we really need the standard to link things together.
> > We need to be very sensitive to increases in complexity or we will loose
> > new contributors.
> >
> >
> >
> > >
> > > REQ4) committer may collaborate on branches.
> > >
> > > REC5) While PR's are preferred, patches may be accepted.
> > > DREC5.1) Committers receiving patches shall apply them to a new
> branch
> > > (per REQ3) and open a PR.
> > > REC5.1) Committers shall attribute work to the person submitting
> patch
> > >
> > > REC6) All PR requires a review.
> > > DREC6.1) the project shall publish a list of subject
> experts
> > > REC6.1) Request for review shall be made via email to subject
> experts or
> > > PPMC.
> > > REC6.1.1) Multiple reviewers shall be required on OS internals.
> > > REC6.1.2) Multiple reviewers may be required on NON OS internals.
> > >
> > >
> > > David
> >
> >
> > The rest sounds good. I would say let's start minimal and work up if we
> > find quality or complexity issues.
> >
> > --Brennan
> >
>
> The purpose was accommodating the "repos must be on the ASF infrastructure
> edict"[1] .
> Which I believe, please correct me if I am wrong, is pure git???
>
> Therefore I was removing the dependency of githubs features on the work
> flow.
> The only way I know how to do this in pure git is: by tag, branch name or
> SHAL
>
> Since we can not use strike out in this environment:
> Would you be ok with adding your edits in a diff like form?
>
> I.e.
>
> -REQ3.1) naming conventions shall reflect lineage:
> +REQ3.1) naming conventions may reflect lineage:
>
> [1] mentor's email re:50 years support and how the internet changes
>
> Also having to ignore github workfow for the sake of only being top down
> herein would not be my approach, but I am tying to accommodate everyone
> input.
>
> David
>
>
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
> Can we simplify the workflow to avoid creating so many temp branching
> in the official repo:
> 1.User submit PR against the master
> 2.Run style, build and test through CI
> 3.Review and comment PR by committer
> 4.Merge PR into master if all check pass
> User may have to repeat step 1 to 3 several time before PR finally accept.
> Note 1: step 2 may be done by committer manually before the tool is ready.
> Note 2: we can refine how many approvement is required before PR can be merge.
That is basically what I was doing on the Bitbucket repository. But I
will not try to maintain the ASF repository in this fashion. No one
should expect me to dispose of any patches or PRs. I don't do that anymore.
Since I will not longer be disposing of patches or PRs. I propose we
use what Justin called "scratch what itches," meaning that if a
committer see a commit come by that interests him/her, take the
responsibility of doing steps 1-4. If no one is interested in a change
then the change is just going to have to linger for awhile.
> If user send patch to dev@nuttx.apache.org instead, one of committer
> need convert the patch to PR by the same process too.
> If there has a big feature development, committer could create a
> branch for that after voting in dev list, but the same process should
> apply to this branch like master.
> Actually, this process is almost same as bitbucket or github, many
> developer is already familiar with it:
> https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
> The major difference from David's is that no any temp PR branch is
> created in the official repo.
+1
The change submission part of the workflow must not contain anything
that the unprivileged contributor cannot do. All contributions by
people with privileges must follow the same workflow as for contributors
without privileges.
We could keep a dev branch like Duo implied and all PRs should be
against the dev branch? That would simplify the above. Alan also
suggest this, but he called it a 'stage'. 'dev' is a better name.
Greg
Re: Code review tool
Posted by Disruptive Solutions <di...@gmail.com>.
Nxstyle is really helpfull...
Verstuurd vanaf mijn iPhone
> Op 22 dec. 2019 om 08:05 heeft Abdelatif Guettouche <ab...@gmail.com> het volgende geschreven:
>
> Hi Justin,
>
> Nxstyle is a C file that you can find under tools.
>
> You can build it under any OS.
> Greg is just using Windows.
>
>> On Sun, Dec 22, 2019, 03:50 Justin Mclean <ju...@classsoftware.com> wrote:
>>
>> Hi,
>>
>> Perhaps someone wants to work on making a portable version of this? It
>> seems it would be using for checking PRs and part of the CI system.
>>
>> Thanks,
>> Justin
Re: Code review tool
Posted by Abdelatif Guettouche <ab...@gmail.com>.
Hi Justin,
Nxstyle is a C file that you can find under tools.
You can build it under any OS.
Greg is just using Windows.
On Sun, Dec 22, 2019, 03:50 Justin Mclean <ju...@classsoftware.com> wrote:
> Hi,
>
> Perhaps someone wants to work on making a portable version of this? It
> seems it would be using for checking PRs and part of the CI system.
>
> Thanks,
> Justin
Re: Code review tool
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
Perhaps someone wants to work on making a portable version of this? It seems it would be using for checking PRs and part of the CI system.
Thanks,
Justin
Code review tool
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
I just tool a look at the tool Greg uses from review, and notice it runs an exe:
tools/nxstyle.exe -m 86 $file
So that not going to work for all committers. As I’m not familial with the project, perhaps
i’m missing something.
Where is the source for this tool located?
Thanks,
Justin
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
On 12/21/2019 11:00 AM, Gregory Nutt wrote:
>
>> Can we simplify the workflow to avoid creating so many temp branching
>> in the official repo:
>> 1.User submit PR against the master
>> 2.Run style, build and test through CI
We have no capability to test via CI at present. We don't even have the
requirements that would define test through CI
>> 3.Review and comment PR by committer
>> 4.Merge PR into master if all check pass
>> User may have to repeat step 1 to 3 several time before PR finally
>> accept.
>> Note 1: step 2 may be done by committer manually before the tool is
>> ready.
>> Note 2: we can refine how many approvement is required before PR can
>> be merge.
>
> That is basically what I was doing on the Bitbucket repository. But I
> will not try to maintain the ASF repository in this fashion. No one
> should expect me to dispose of any patches or PRs. I don't do that
> anymore.
I have attached a script called review.sh. I have sent this before.
This is the script that use for doing basic stylistic review of
changes. It is very primitive since it was only intended for my
personal use. but you can see the basic things I did. Most the things
only got un-commented if nxstyle complained about something. indent.sh
was only used if the nxstyle complaints were excessive.
Greg
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
> Can we simplify the workflow to avoid creating so many temp branching
> in the official repo:
> 1.User submit PR against the master
> 2.Run style, build and test through CI
> 3.Review and comment PR by committer
> 4.Merge PR into master if all check pass
> User may have to repeat step 1 to 3 several time before PR finally accept.
> Note 1: step 2 may be done by committer manually before the tool is ready.
> Note 2: we can refine how many approvement is required before PR can be merge.
That is basically what I was doing on the Bitbucket repository. But I
will not try to maintain the ASF repository in this fashion. No one
should expect me to dispose of any patches or PRs. I don't do that anymore.
Since I will not longer be disposing of patches or PRs. I propose we
use what Justin called "scratch what itches," meaning that if a
committer see a commit come by that interests him/her, take the
responsibility of doing steps 1-4. If no one is interested in a change
then the change is just going to have to linger for awhile.
> If user send patch to dev@nuttx.apache.org instead, one of committer
> need convert the patch to PR by the same process too.
> If there has a big feature development, committer could create a
> branch for that after voting in dev list, but the same process should
> apply to this branch like master.
> Actually, this process is almost same as bitbucket or github, many
> developer is already familiar with it:
> https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
> The major difference from David's is that no any temp PR branch is
> created in the official repo.
+1
The change submission part of the workflow must not contain anything
that the unprivileged contributor cannot do. All contributions by
people with privileges must follow the same workflow as for contributors
without privileges.
We could keep a dev branch like Duo implied and all PRs should be
against the dev branch? That would simplify the above. Alan also
suggest this, but he called it a 'stage'. 'dev' is a better name.
Greg
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
-------- Forwarded Message --------
Subject: Re: [DISCUSS - NuttX Workflow]
Date: Thu, 19 Dec 2019 13:09:10 -0500
From: Nathan Hartman <ha...@gmail.com>
Reply-To: dev@nuttx.apache.org
To: dev@nuttx.apache.org
On Thu, Dec 19, 2019 at 8:30 AM Gregory Nutt <sp...@gmail.com> wrote:
> On Thu, Dec 19, 2019 at 3:32 AM Sebastien Lorquet <se...@lorquet.fr> wrote:
>> But the endless list of complex git commands with additional options is probably
>> a blocker for many other people too.
>>
>> I dont even want to read it all.
>
> You and me both. The near term objective of the PPMC is just to come up
> with a list -- maybe one page double spaced -- that just summarizes the
> steps that changes will undergo going from a patch (or PR) to being
> merged into master. Should be pretty simple. These would be the
> "functional" requirements of the workflow.
>
> I think only 5 emails in the whole list really address these functional
> requirements.
Let me add a 6th... (Without mentioning any "stupid" SCMs.)
One thing missing from our earlier discussions is to decide how many
approvals a change requires. I think this varies by area of the code
being changed.
As a starting point for further discussion, I suggest something along
these lines:
Changes that affect the build system should require three +1 binding
votes and no vetoes from PMC members PLUS at least one report that
NuttX builds successfully on each supported platform: Windows, Mac,
Unix, and no reports of breakage caused by the change. Builds on
Windows using a Unix compatibility layer would be considered Unix for
this purpose. Any member of the community should be able to report
whether it builds successfully and on which platform. Between the
submitter of the patch, PMC members, and testers, this means that at
least 7 pairs of eyes looks at any change to the build system. This
high number is necessary because breakage there affects everyone and
is very disruptive!
Changes to code that affect the core of the OS should require three +1
binding votes and no vetoes from PMC members and should be accompanied
by some rationale or justification for the change. If applicable,
supporting data should be provided, e.g., if it's supposed to improve
performance, is this backed up by measurements?
Changes to code in MCU architectural support, board support, or features
in the periphery of the OS should be at the discretion of the
committer. Committers should use their best judgment and are
encouraged to discuss anything they're not sure about. But these
changes don't require as much oversight. These changes are much more
limited in their exposure. They are usually developed by someone to
scratch their own itch. Also these are allowed to be feature-
incomplete: e.g., it is okay to have partial board support.
In the apps repository: Changes to code in core apps (such as NSH)
should require two +1 binding votes and no vetoes.
Changes to other non-core areas of apps are at the discretion of the
committer.
Notwithstanding all of the above, there is the concept of an "obvious
fix." Any committer may fix things like obvious typos, misspellings,
grammar mistakes in comments, code formatting violations, that do not
change the behavior of the code, without the need for voting and
approvals, etc. Committers are expected to exercise their best
judgment here.
It is expected that when someone votes +1 on a change, it means that:
* They have studied the change
* Verified that the change meets INVIOLABLES.
* Verified that it does not break POSIX compatibility or OS
architectural boundaries
* Done testing if feasible
* Weighed any input from the community
Please remember, the above are NOT rules, the above is a starting
point for discussion as we hash out our requirements.
Please participate, offer your thoughts, criticisms, etc.
Thanks,
Nathan
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
-------- Forwarded Message --------
Subject: Re: [DISCUSS - NuttX Workflow]
Date: Thu, 19 Dec 2019 12:32:31 -0600
From: Gregory Nutt <sp...@gmail.com>
To: dev@nuttx.apache.org
>> I think only 5 emails in the whole list really address these functional
>> requirements.
> Let me add a 6th... (Without mentioning any "stupid" SCMs.)
>
> One thing missing from our earlier discussions is to decide how many
> approvals a change requires. I think this varies by area of the code
> being changed.
>
> As a starting point for further discussion, I suggest something along
> these lines:
>
> Changes that affect the build system should require three +1 binding
> votes and no vetoes from PMC members PLUS at least one report that
> NuttX builds successfully on each supported platform: Windows, Mac,
> Unix, and no reports of breakage caused by the change. Builds on
> Windows using a Unix compatibility layer would be considered Unix for
> this purpose. Any member of the community should be able to report
> whether it builds successfully and on which platform. Between the
> submitter of the patch, PMC members, and testers, this means that at
> least 7 pairs of eyes looks at any change to the build system. This
> high number is necessary because breakage there affects everyone and
> is very disruptive!
>
> Changes to code that affect the core of the OS should require three +1
> binding votes and no vetoes from PMC members and should be accompanied
> by some rationale or justification for the change. If applicable,
> supporting data should be provided, e.g., if it's supposed to improve
> performance, is this backed up by measurements?
>
> Changes to code in MCU architectural support, board support, or features
> in the periphery of the OS should be at the discretion of the
> committer. Committers should use their best judgment and are
> encouraged to discuss anything they're not sure about. But these
> changes don't require as much oversight. These changes are much more
> limited in their exposure. They are usually developed by someone to
> scratch their own itch. Also these are allowed to be feature-
> incomplete: e.g., it is okay to have partial board support.
>
> In the apps repository: Changes to code in core apps (such as NSH)
> should require two +1 binding votes and no vetoes.
>
> Changes to other non-core areas of apps are at the discretion of the
> committer.
>
> Notwithstanding all of the above, there is the concept of an "obvious
> fix." Any committer may fix things like obvious typos, misspellings,
> grammar mistakes in comments, code formatting violations, that do not
> change the behavior of the code, without the need for voting and
> approvals, etc. Committers are expected to exercise their best
> judgment here.
>
> It is expected that when someone votes +1 on a change, it means that:
>
> * They have studied the change
>
> * Verified that the change meets INVIOLABLES.
>
> * Verified that it does not break POSIX compatibility or OS
> architectural boundaries
>
> * Done testing if feasible
>
> * Weighed any input from the community
>
> Please remember, the above are NOT rules, the above is a starting
> point for discussion as we hash out our requirements.
>
> Please participate, offer your thoughts, criticisms, etc.
>
> Thanks,
> Nathan
Those sound like good rules of thumb to me. Certainly there are parts
of the OS that require more care and have broader impact that others.
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
> Step 4
>
> Ultimately, it is the committer who is responsible for assuring that
> (1) the change is technically correct, complete, and of the highest
> quality. And that (2) the change is consistent with all of the
> principles of the Inviolables: The change must not violate the
> portable POSIX interface, the change must conform to the architectural
> principles of the OS, the change must not expose any platform
> dependencies that would have any impact on other users of NuttX.
>
>
> At this point, the committer should be confident that the change is in
> full compliance with the coding standard and will not break the build.
>
> Then there is Justin Mclean's response to this. I cannot find it, but
> it is where the phrase "Scratch what itches" comes from. In Step 4,
> Justin recommend not being so former. In most Apache projects,
> commiters just "scratch what itches" meaning that they review and
> merge commits that are interesting to them.
>
Found this too:
From Justin Mclean <ju...@classsoftware.com>
Subject Re: [DISCUSS - NuttX Workflow]
Date Wed, 18 Dec 2019 21:46:09 GMT
HI,
> 3.
> PMC should triage and assign the change to a committer. PMC may
> also review for conformance with the Inviolables If this review
> fails, the change is declined.
Most of the Apache projects I’m on let committers select what they what to review and work
on rather than being assigned it. It’s often referred to as “scratch your own itch”.
Tha not to say that this project can’t do it differently, but the workflow may need to consider
that people are volunteers and their availability may vary.
Thanks,
Justin
Now I think I have reposted EVERY email that proposes specific workflow
requirements. There are several more that comment on these, but I will
leave that as an exercise for anyone interested.
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
There is also this proposed change to the work flow that I did not
include only because I don't understand it.
Proposed Steps from Contribution to Commit
I think the work flow should be like this:
1.
Use git Pre-commit: on developers machine. To run Code-Style (CS)
and formatting (EOL checks)
1.
This git script is called on commit that runs the formatting
tool on all the changed files.
A formatting tool is needed. It has to be absolute or categorise
violations as warnings and errors. The class of warnings could be long
line length.
The formatting tool should be able to show a diff of the working
directory and suggested changes. Ideally it offers a command line
suggestion to fix tie formatting of the subject file.
The configuration or tool must live in the repo. In the case of the tool
it must be built prior to commit by the build or the pre-comit hook.
Note: In the absence of such a tool a y/n prompt can be issued. But this
will lead to push hecks failing.
2.
PR or patch received (where? how? Via incubator email?
1.
If using github with git box sync - this would be a PR.
3.
The PR and/or pushes to the branch Ttriggers automated checking:
1.
Verify that it follows the coding standard, and
2.
1.
This is the same tool used locally for the pre-commit.
3.
vVerify that the build is not broken.This is a parallel
distributed build.
1.
Compile: Linux
2.
Compile: Windows
3.
Compile: MacOX
4.
???
Ideally the push front end script will Auto detect the affected
subsystem and arch/board and build all the configs for it first.
If either failThese failures, ask the contributor to fix the problem and
resubmit push the changes. (This is automatic in the tooling of github.)
On 12/21/2019 1:26 PM, Gregory Nutt wrote:
>
> As you can see, I have been tried to forward relevant emails from this
> thread. There are at least two and maybe three that I cannot find.
>
> First there is the text which I appended to Nathan's workflow:
>
> Proposed Work Flow
>
>
> Proposed Steps from Contribution to Commit
>
> I think the work flow should be like this:
>
> 1.
>
> PR or patch received (where? how? Via incubator email?
>
> 2.
>
> Triggers automated checking:
>
> 1.
>
> Verify that it follows the coding standard, and
>
> 2.
>
> verify that the build is not broken.
>
> If either fail, ask the contributor to fix the problem and resubmit
> the change.
>
> 3.
>
> PMC should triage and assign the change to a committer. PMC may
> also review for conformance with the Inviolables If this review
> fails, the change is declined.
>
> 4.
>
> Committer performs final review for technical correctness and
> conformance to the Inviolables. If this review fails, the change
> is declined otherwise the committer commits the change.
>
> 5.
>
> 2:42 PM <https://nuttx.slack.com/archives/GM2JH0P3M/p1575146565176000>
>
>
> Step 1
>
> Changes should include some information about how to test the change.
> For modifications to code that is tested by existing configurations,
> we would need to know the relevant configurations settings. From that
> we should be able to select a set of relevant test configurations.
>
>
> If the change is a new feature, then it may not be testable using any
> existing configuration. In that case, we will have to insist that the
> change be accompanied by a configuration that can be used for testing.
>
>
> Step 2
>
> For now we just need this minimum, but this should extend in the
> future as we aim for a higher level of quality assurance.
>
> Step 2a)The NuttX style verification tool, nxstyle, should be used to
> check coding style. If the submission does not follow the NuttX
> coding style, we will need to ask the contributor to update the change
> so that it does.
>
> Nxstyle is an imperfect tool, however. We probably need to manually
> check any failed output to verify that the failures are not false alarms.
>
> Step 2b) The brute force Jenkins-style testing is not useful here.
> Rather, we need a smarter build. We need to build configurations that
> ACTUALLY build the code that is changed by the contribution. Per step
> 1) the contributor has either provided a new test configuration (which
> should be included) as a part of the change, or 2) the contributor has
> provided the relevant configuration settings for testing the change.
>
> In the latter case, we should be able to build a test configuration
> list by selecting existing configuration that include these
> configuration settings.
>
> Step 2c) This is where we may want to add hardware-in-the-loop
> testing with a reference board in the future.
>
>
> Step 3
>
> There should be a list of all committers with the areas in which they
> have the best expertise. Assigning a change to a committer should be
> simply picking the person with the best expertise, but also accounting
> for any backlog. Other committers may need to take up the slack.
>
>
> Step 4
>
> Ultimately, it is the committer who is responsible for assuring that
> (1) the change is technically correct, complete, and of the highest
> quality. And that (2) the change is consistent with all of the
> principles of the Inviolables: The change must not violate the
> portable POSIX interface, the change must conform to the architectural
> principles of the OS, the change must not expose any platform
> dependencies that would have any impact on other users of NuttX.
>
>
> At this point, the committer should be confident that the change is in
> full compliance with the coding standard and will not break the build.
>
> Then there is Justin Mclean's response to this. I cannot find it, but
> it is where the phrase "Scratch what itches" comes from. In Step 4,
> Justin recommend not being so former. In most Apache projects,
> commiters just "scratch what itches" meaning that they review and
> merge commits that are interesting to them.
>
> There is possibly a third email that I cannot find from David Sidrane
> that had some thoughts about the work flow. I can't find it and I
> don't recall the content. If someone else knows the email that I am
> referring to, it would be good to have on this thread as well.
>
> Greg
>
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
>> Now I remember, David was proposing a C beautifier to be used in the
>> work flow. I cannot find that one right now.
>>
Related:
Gregory Nutt <sp...@gmail.com>
Subject Re: [DISCUSS - NuttX Workflow]
Date Wed, 18 Dec 2019 13:36:24 GMT
> Option d) Make minimal coding standard changes that can be 100% supported by option
a.*
>
> *) Greg suggested this in the bar at NuttX2019 - caveat it was in the BAR!
No one should be held accountable for what the say in a bar 8-)
A lot depends on the nature of the coding standard change. If you make
small coding standard changes, the existing indent.sh is nearly perfect
(nearly). As a general principle, I think that the coding standard
should not change to match to a tool. Changing code to match a tool is
a little bothersome as a concept because it is the "tag wagging the dog."
The Inviolables.txt addresses this:
o Strict conformance to the NuttX coding style. No "revolutionary"
changes to the coding standard (but perhaps some "evolutionary"
changes).
That is open to some interpretation. I'm not sure if fixing the
behavior of a tool by changing the coding standard is correctly
"evolutionary" or not. it is more or a kludge. The Inviolables also say:
o Expediency is not a justification for violating the coding standard.
Together, I would take that to mean that we should consider changing the
coding standard only if we have exhausted all other possibilities. If
is is difficult to make a pretty printer behave properly, then that is
not enough. It must be impossible. "Short cuts" is the enemy in the
Inviolables.txt
I would add that one person cannot change the Inviolables or any NuttX
standards. That really must be a vote of the PPMC. And, I think like a
constitutional change or an impeachment, it probably should require more
than a simple majority to change any standard. If a super-majority is
in favor of any change, that the other just need to accept it.
Greg
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
On 12/21/2019 1:32 PM, Gregory Nutt wrote:
>
>> As you can see, I have been tried to forward relevant emails from
>> this thread. There are at least two and maybe three that I cannot
>> find. ...
>>
>> There is possibly a third email that I cannot find from David Sidrane
>> that had some thoughts about the work flow. I can't find it and I
>> don't recall the content. If someone else knows the email that I am
>> referring to, it would be good to have on this thread as well.
>
> Now I remember, David was proposing a C beautifier to be used in the
> work flow. I cannot find that one right now.
>
I found it:
David Sidrane <da...@apache.org>
Subject Re: [DISCUSS - NuttX Workflow]
Date Wed, 18 Dec 2019 10:15:55 GMT
Hi,
Sharing my thoughts here for discussion.
=== Source code checking ====
Prior to submission, the submission shall be checked by a source code beatify-er.
REQ1: The submission shall not be possible without a local check passing.
REQ2: A tool shall be used to check the NuttX coding standard.
REQ3: A tool shall be used to check for ASF licence compliance.
REQ4: A tool shall be used to check for blank lines at the end of files.
DREQ1) An gold standard source code file need to be created to validate tool.
Option a) Enhance nxstyle to
i. To be complete
ii. Support class of errors: errors, warnings, info
iii. Support format options that fixes the files
iv. At a minimum give compiler output error message that allow rapid fixing of the source
in a compiler output aware editor. vi, UE, VC, Eclipse.....
Options b) use a mature tool such as Astyle, Uncrutstify, clang format - train it with https://github.com/mikr/whatstyle.
Option c) Cascade a combination of a & b to get the last 2% that option a can not.
Option d) Make minimal coding standard changes that can be 100% supported by option a.*
*) Greg suggested this in the bar at NuttX2019 - caveat it was in the BAR!
On 2019/12/17 09:36:28, david.sidrane@gmail.com wrote:
> [DISCUSS - NuttX Workflow]
>
> I am creating this thread to discuss what we as a community would like to
> have as NuttX Workflow. I have also created [REQUIREMENTS- NuttX Workflow]
> I am asking us to not add discussion to [REQUIREMENTS- NuttX Workflow].
> Please do that here.
>
> As this discussion evolves we shall create requirements and add them
> to the [REQUIREMENTS-
> NuttX Workflow] thread.
>
> Please use [DISCUSS - NuttX Workflow] to propose and discuss the ideas
> and experiences
> you have to offer.
>
> Be detailed; give examples, list pros and cons, why you like it and why you
> don't.
>
> Then after the requirements are gathered in one place and discussed here
> then can vote on them.
>
> Thank you.
>
> David
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
> As you can see, I have been tried to forward relevant emails from this
> thread. There are at least two and maybe three that I cannot find. ...
>
> There is possibly a third email that I cannot find from David Sidrane
> that had some thoughts about the work flow. I can't find it and I
> don't recall the content. If someone else knows the email that I am
> referring to, it would be good to have on this thread as well.
Now I remember, David was proposing a C beautifier to be used in the
work flow. I cannot find that one right now.
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
As you can see, I have been tried to forward relevant emails from this
thread. There are at least two and maybe three that I cannot find.
First there is the text which I appended to Nathan's workflow:
Proposed Work Flow
Proposed Steps from Contribution to Commit
I think the work flow should be like this:
1.
PR or patch received (where? how? Via incubator email?
2.
Triggers automated checking:
1.
Verify that it follows the coding standard, and
2.
verify that the build is not broken.
If either fail, ask the contributor to fix the problem and resubmit
the change.
3.
PMC should triage and assign the change to a committer. PMC may
also review for conformance with the Inviolables If this review
fails, the change is declined.
4.
Committer performs final review for technical correctness and
conformance to the Inviolables. If this review fails, the change is
declined otherwise the committer commits the change.
5.
2:42 PM <https://nuttx.slack.com/archives/GM2JH0P3M/p1575146565176000>
Step 1
Changes should include some information about how to test the change.
For modifications to code that is tested by existing configurations, we
would need to know the relevant configurations settings. From that we
should be able to select a set of relevant test configurations.
If the change is a new feature, then it may not be testable using any
existing configuration. In that case, we will have to insist that the
change be accompanied by a configuration that can be used for testing.
Step 2
For now we just need this minimum, but this should extend in the future
as we aim for a higher level of quality assurance.
Step 2a)The NuttX style verification tool, nxstyle, should be used to
check coding style. If the submission does not follow the NuttX coding
style, we will need to ask the contributor to update the change so that
it does.
Nxstyle is an imperfect tool, however. We probably need to manually
check any failed output to verify that the failures are not false alarms.
Step 2b) The brute force Jenkins-style testing is not useful here.
Rather, we need a smarter build. We need to build configurations that
ACTUALLY build the code that is changed by the contribution. Per step
1) the contributor has either provided a new test configuration (which
should be included) as a part of the change, or 2) the contributor has
provided the relevant configuration settings for testing the change.
In the latter case, we should be able to build a test configuration list
by selecting existing configuration that include these configuration
settings.
Step 2c) This is where we may want to add hardware-in-the-loop testing
with a reference board in the future.
Step 3
There should be a list of all committers with the areas in which they
have the best expertise. Assigning a change to a committer should be
simply picking the person with the best expertise, but also accounting
for any backlog. Other committers may need to take up the slack.
Step 4
Ultimately, it is the committer who is responsible for assuring that (1)
the change is technically correct, complete, and of the highest
quality. And that (2) the change is consistent with all of the
principles of the Inviolables: The change must not violate the portable
POSIX interface, the change must conform to the architectural principles
of the OS, the change must not expose any platform dependencies that
would have any impact on other users of NuttX.
At this point, the committer should be confident that the change is in
full compliance with the coding standard and will not break the build.
Then there is Justin Mclean's response to this. I cannot find it, but
it is where the phrase "Scratch what itches" comes from. In Step 4,
Justin recommend not being so former. In most Apache projects,
commiters just "scratch what itches" meaning that they review and merge
commits that are interesting to them.
There is possibly a third email that I cannot find from David Sidrane
that had some thoughts about the work flow. I can't find it and I don't
recall the content. If someone else knows the email that I am referring
to, it would be good to have on this thread as well.
Greg
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
-------- Forwarded Message --------
Subject: Re: [DISCUSS - NuttX Workflow]
Date: Wed, 18 Dec 2019 11:55:46 -0500
From: Nathan Hartman <ha...@gmail.com>
Reply-To: dev@nuttx.apache.org
To: dev@nuttx.apache.org
On Wed, Dec 18, 2019 at 11:18 AM Gregory Nutt <sp...@gmail.com> wrote:
> Requirements specification is a top-down activity. It is only driven by
> end users needs and project objects. NOT by implementation. That is
> the nature of System Engineering: top-down
Just throwing some thoughts out here as a starting point for that
top-down discussion:
Users of NuttX can:
* Use NuttX with our Apps
* Use NuttX by itself and provide their own Apps
For the toolchain, they can:
* Use the toolchains we provide with buildroot
* Use their own toolchains
They can get NuttX and/or apps:
* From Git
* From source release tarballs
If getting from Git, they can:
* Live on the bleeding edge with Master
* Work from a branch or tag for more stability
When they wish to contribute, they can do so:
* Via a pull request
* Via a patch transmitted to us by some method
Regardless of the method, we would convert the pull request and/or
patch into a form that is useful for us. For example, if we work with
pull requests and we are given a patch, we convert the patch into a
pull request.
Contributions may be based on:
* Master.
* Or the latest release. When contributions are based on the latest
release, we should rebase them onto master.
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
Haitao Liu <li...@gmail.com>
Subject Re: [DISCUSS - NuttX Workflow]
Date Wed, 18 Dec 2019 09:51:45 GMT
How about just keep two separate git repositories (apps and nuttx
projects) instead
of add a parent knot repo with apps and nuttx as sub-modules?
As to jenkins CI, I haven’t found proper github plugin to get PRs from
multiple repos(especially PRs dependency in apps & nuttx ) in one Jenkins
job. Before that, I wonder whether we could keep it simple and
directly, create
one jenkins job for apps and another jenkins job for nuttx to process PR
trigger accordingly. Just make sure the jenkins pipeline or build script
to sync both apps and nuttx repos, then pick the apps or nuttx PR to do
full build.
Since nuttx and apps projects keeps same as before, developers adapt to
github workflow as usual:
1 fork the official apache nuttx & apps projects in github
2 git clone your fork projects locally
3 edit locally and then git commit to local branch
4 git push to your github fork nuttx/apps branch
5 issue one pull request from your fork nuttx/apps to apache nuttx/apps
master branch
6 jenkins CI auto-trigger: style check, build or test, if failed, go to
step 3, continue 3 ~ 7
7 PMC start to review PR, review ok, merge to master; or review failed, go
to step 3, continue 3~7
Detailed info about GitHub workflow:
https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
<da...@gmail.com> 于2019年12月17日周二 下午5:36写道：
> [DISCUSS - NuttX Workflow]
>
> I am creating this thread to discuss what we as a community would like to
> have as NuttX Workflow. I have also created [REQUIREMENTS- NuttX Workflow]
> I am asking us to not add discussion to [REQUIREMENTS- NuttX Workflow].
> Please do that here.
>
> As this discussion evolves we shall create requirements and add them
> to the [REQUIREMENTS-
> NuttX Workflow] thread.
>
> Please use [DISCUSS - NuttX Workflow] to propose and discuss the ideas
> and experiences
> you have to offer.
>
> Be detailed; give examples, list pros and cons, why you like it and why you
> don't.
>
> Then after the requirements are gathered in one place and discussed here
> then can vote on them.
>
> Thank you.
>
> David
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> Please point me to where this work should be done and any guide you have on how to use Confluence.
NuttX space is here [1] it's easy to use, so you probably don’t need documentation on how to use it, but if you do it can be found here. [2]
Currently only PPMC members has permission to add/edit pages, so if you’re not on the PPMC just tell us what your user name is and we’ll give you permission.
Thanks,
Justin
1. https://cwiki.apache.org/confluence/display/NUTTXTEST/Nuttx
2. https://confluence.atlassian.com/confcloud/confluence-cloud-documentation-home-941614888.html
P.S The name/key will change to NUTTX in the near future.
Re: [CALL for TOP Down workflow Requirements]
Posted by David Sidrane <da...@apache.org>.
Thank you Nathan!
On 2019/12/22 06:01:55, Nathan Hartman <ha...@gmail.com> wrote:
> On Sat, Dec 21, 2019 at 7:26 PM Gregory Nutt <sp...@gmail.com> wrote:
>
> > Let me start by stating a few [obvious] objectives:
> > Keep things simple for those NuttX users who prefer to work with a zip’d
> > release.
> > provide best-practice tools and workflow to maximize productivity of
> > developers living on
> > the bleeding edge.
> > define a disciplined process that insures the continued quality of the
> > project.
> >
> > As we fill in the details, this discussion will naturally blend in
> > specifics of implementation
> > and tools — I expect “git” might come up in the discussions ;)
>
>
> At this point, much has been written in this and other threads.
>
> Now I recommend that we should have a Confluence page where the information
> can be edited to make it:
>
> * Plain English
> * Flow well
> * Readable
> * Coherent
> * Specific
> * Not assume knowledge
> * In one easy to find place
>
> I say "I recommend that we should" instead of just going ahead and creating
> that Confluence page because I want to ensure that this happens with
> community agreement.
>
> Rationale for creating the document: I don't want or expect anyone to
> memorize our workflow, nor to go digging all over the place to piece
> together what it is. I want it documented clearly so that veteran
> contributors and total newbies alike will be able to understand exactly
> what to do. I also want this documented for purpose of on-boarding future
> committers and so that committers will know what is expected of them
> whenever they commit. And furthermore I want it in a clear document that we
> can officially vote on to make it our "blessed" workflow, until such time
> as we decide to make changes and vote to update the "blessed" process.
>
> The document should flow in a manner that makes information easy to find. I
> suggest to organize it as follows:
>
> 1. Overview. This section defines "WHAT" the steps of the workflow are.
> This is a simple bulleted or numbered list. No rationale, no git jargon, no
> DevOps nonsense, just clear plain English. Where is the code. What basic
> steps take place to apply changes to it. Greg literally wrote this list a
> few emails ago and it contains 80% of what should be in that list. It needs
> minimal improvement.
>
> 2. How To Submit Changes For Review. This section defines the "HOW" of the
> workflow for ANYONE who wants to get a change into NuttX, whether committer
> or not. Committers do not get to bypass this process. This section should
> document: How to obtain a copy of the code. What steps to take before
> beginning work on a change. Once you've made your change and want to
> contribute it, what steps to take to turn it into a PR or patch. How to
> submit the PR or patch to us? We should NOT assume knowledge. If a step
> requires using git, then give the exact git command followed by an
> explanation of every element of that command, so that anyone who knows how
> to enter a command in a terminal with zero prior knowledge of git will be
> able to understand exactly how to issue that git command and exactly what
> it will do. I want to make it straightforward and easy for a HARDWARE
> engineer to be able to submit changes.
>
> 3. Criteria For Acceptance. This section defines what sorts of things
> committers will examine and verify before allowing changes into NuttX.
> First, the universal requirements that apply to all parts of NuttX. This
> includes INVIOLABLES, coding standard, rules that govern clean
> architecture, POSIX compliance, not breaking the build, etc. The word
> INVIOLABLES should be a link to that file. After the universal
> requirements, there should be requirements by area. Requirements for
> boards. Requirements for drivers. Requirements for the scheduler.
> Requirements for architectural support. Etc. All of the checks in this
> section can be performed manually by a committer for now. This section
> should be documented clearly and specifically enough that it can directly
> be used as the specification of automated checks to implement in a CI
> system.
>
> 4. Reference For Committers. This section explains to committers how to
> carry out all the steps to process a proposed change from start to finish.
> "Start" means a patch or a PR arrived. If a patch, how to convert it into a
> PR. "Finish" can mean either applying the change to master, or reject the
> change / send it back to the submitter for additional work. And all steps
> in between. This section (item #4) is a continuation of item #2. Item #2
> explained how anyone submits a proposed change for review. Now we explain
> what happens next. Like item #2, we should NOT assume knowledge. If a step
> requires using git, then give the exact git command followed by an
> explanation of every element of that command. This is not excessive. This
> will help on-boarding of new committers as well as help veteran committers
> avoid mistakes.
>
> 5. Rationale. This section explains the "WHY" behind all of the above. So
> that people won't cut an inch off each end of a ham without knowing why.
>
> Cheers,
> Nathan
>
This makes perfect sense. It is well thought out and spot on. It is inviting and I want to be part of it.
Your prior experience with the Apache Way and using its resources such as Confluence are a great asset to this team
I am going to assume this will be voted for by all members. I would like to get up to speed on using Confluence.
Please point me to where this work should be done and any guide you have on how to use Confluence.
David
Re: [CALL for TOP Down workflow Requirements]
Posted by Nathan Hartman <ha...@gmail.com>.
On Sat, Dec 21, 2019 at 7:26 PM Gregory Nutt <sp...@gmail.com> wrote:
> Let me start by stating a few [obvious] objectives:
> Keep things simple for those NuttX users who prefer to work with a zip’d
> release.
> provide best-practice tools and workflow to maximize productivity of
> developers living on
> the bleeding edge.
> define a disciplined process that insures the continued quality of the
> project.
>
> As we fill in the details, this discussion will naturally blend in
> specifics of implementation
> and tools — I expect “git” might come up in the discussions ;)
At this point, much has been written in this and other threads.
Now I recommend that we should have a Confluence page where the information
can be edited to make it:
* Plain English
* Flow well
* Readable
* Coherent
* Specific
* Not assume knowledge
* In one easy to find place
I say "I recommend that we should" instead of just going ahead and creating
that Confluence page because I want to ensure that this happens with
community agreement.
Rationale for creating the document: I don't want or expect anyone to
memorize our workflow, nor to go digging all over the place to piece
together what it is. I want it documented clearly so that veteran
contributors and total newbies alike will be able to understand exactly
what to do. I also want this documented for purpose of on-boarding future
committers and so that committers will know what is expected of them
whenever they commit. And furthermore I want it in a clear document that we
can officially vote on to make it our "blessed" workflow, until such time
as we decide to make changes and vote to update the "blessed" process.
The document should flow in a manner that makes information easy to find. I
suggest to organize it as follows:
1. Overview. This section defines "WHAT" the steps of the workflow are.
This is a simple bulleted or numbered list. No rationale, no git jargon, no
DevOps nonsense, just clear plain English. Where is the code. What basic
steps take place to apply changes to it. Greg literally wrote this list a
few emails ago and it contains 80% of what should be in that list. It needs
minimal improvement.
2. How To Submit Changes For Review. This section defines the "HOW" of the
workflow for ANYONE who wants to get a change into NuttX, whether committer
or not. Committers do not get to bypass this process. This section should
document: How to obtain a copy of the code. What steps to take before
beginning work on a change. Once you've made your change and want to
contribute it, what steps to take to turn it into a PR or patch. How to
submit the PR or patch to us? We should NOT assume knowledge. If a step
requires using git, then give the exact git command followed by an
explanation of every element of that command, so that anyone who knows how
to enter a command in a terminal with zero prior knowledge of git will be
able to understand exactly how to issue that git command and exactly what
it will do. I want to make it straightforward and easy for a HARDWARE
engineer to be able to submit changes.
3. Criteria For Acceptance. This section defines what sorts of things
committers will examine and verify before allowing changes into NuttX.
First, the universal requirements that apply to all parts of NuttX. This
includes INVIOLABLES, coding standard, rules that govern clean
architecture, POSIX compliance, not breaking the build, etc. The word
INVIOLABLES should be a link to that file. After the universal
requirements, there should be requirements by area. Requirements for
boards. Requirements for drivers. Requirements for the scheduler.
Requirements for architectural support. Etc. All of the checks in this
section can be performed manually by a committer for now. This section
should be documented clearly and specifically enough that it can directly
be used as the specification of automated checks to implement in a CI
system.
4. Reference For Committers. This section explains to committers how to
carry out all the steps to process a proposed change from start to finish.
"Start" means a patch or a PR arrived. If a patch, how to convert it into a
PR. "Finish" can mean either applying the change to master, or reject the
change / send it back to the submitter for additional work. And all steps
in between. This section (item #4) is a continuation of item #2. Item #2
explained how anyone submits a proposed change for review. Now we explain
what happens next. Like item #2, we should NOT assume knowledge. If a step
requires using git, then give the exact git command followed by an
explanation of every element of that command. This is not excessive. This
will help on-boarding of new committers as well as help veteran committers
avoid mistakes.
5. Rationale. This section explains the "WHY" behind all of the above. So
that people won't cut an inch off each end of a ham without knowing why.
Cheers,
Nathan
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
Forwarded:
"David S. Alessio" <da...@gmail.com>
Subject Re: [DISCUSS - NuttX Workflow]
Date Thu, 19 Dec 2019 00:33:00 GMT
We’ve digressed a bit on this thread. Let’s see if we can reboot DavidS’ Workflow thread
and keep the thread on topic.
Let me start by stating a few [obvious] objectives:
Keep things simple for those NuttX users who prefer to work with a zip’d release.
provide best-practice tools and workflow to maximize productivity of developers living on
the bleeding edge.
define a disciplined process that insures the continued quality of the project.
As we fill in the details, this discussion will naturally blend in specifics of implementation
and tools — I expect “git” might come up in the discussions ;)
Cheers,
-david
Re: [CALL for TOP Down workflow Requirements]
Posted by Alan Carvalho de Assis <ac...@gmail.com>.
+1
I agree that dev or develop or development is a better name. I just
submitted to "stage" because I was doing a test.
On Saturday, December 21, 2019, David Sidrane <Da...@nscdg.com>
wrote:
> +1
>
> -----Original Message-----
> From: Brennan Ashton [mailto:bashton@brennanashton.com]
> Sent: Saturday, December 21, 2019 9:30 AM
> To: dev@nuttx.apache.org
> Subject: Re: [CALL for TOP Down workflow Requirements]
>
> +1 to this. No ci yet so everything "passes" and just gets the commiter
> review. We can define more later as needed
>
> On Sat, Dec 21, 2019, 8:44 AM Xiang Xiao <xi...@gmail.com>
wrote:
>
>> Can we simplify the workflow to avoid creating so many temp branching
>> in the official repo:
>> 1.User submit PR against the master
>> 2.Run style, build and test through CI
>> 3.Review and comment PR by committer
>> 4.Merge PR into master if all check pass
>> User may have to repeat step 1 to 3 several time before PR finally
accept.
>> Note 1: step 2 may be done by committer manually before the tool is
ready.
>> Note 2: we can refine how many approvement is required before PR can be
>> merge.
>> If user send patch to dev@nuttx.apache.org instead, one of committer
>> need convert the patch to PR by the same process too.
>> If there has a big feature development, committer could create a
>> branch for that after voting in dev list, but the same process should
>> apply to this branch like master.
>> Actually, this process is almost same as bitbucket or github, many
>> developer is already familiar with it:
>>
>>
https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
>> The major difference from David's is that no any temp PR branch is
>> created in the official repo.
>>
>> Thanks
>> Xiang
>>
>> On Sat, Dec 21, 2019 at 8:36 PM Gregory Nutt <sp...@gmail.com> wrote:
>> >
>> > This is the mantra we must always follow "support what you users want."
>> > Stay focused on the needs and convenience of the end-user. Always good
>> > advice. If there are complexities dependencies, we should quantine
>> > those complexities and dependencies inside the test architecture. We
>> > give the end-user maximal flexibility in all things.
>> >
>> > Businesses fail that don't listen tho their customers. We will also
>> > fail if we do not listen.
>> >
>> > On 12/21/2019 2:59 AM, Justin Mclean wrote:
>> > > Hi,
>> > >
>> > >> The purpose was accommodating the "repos must be on the ASF
>> infrastructure edict"[1] .
>> > >> Which I believe, please correct me if I am wrong, is pure git???
>> > > Most(?) use git, some also use svn, there might be a couple that
still
>> use cvs. Use of GitHub is not a requirement, but may be convenient.My
>> advice be flexible and support what you users want.
>> > >
>> > > Thanks,
>> > > Justin
>> > >
>> > >
>> >
>>
>
RE: [CALL for TOP Down workflow Requirements]
Posted by David Sidrane <Da...@nscdg.com>.
+1
-----Original Message-----
From: Brennan Ashton [mailto:bashton@brennanashton.com]
Sent: Saturday, December 21, 2019 9:30 AM
To: dev@nuttx.apache.org
Subject: Re: [CALL for TOP Down workflow Requirements]
+1 to this. No ci yet so everything "passes" and just gets the commiter
review. We can define more later as needed
On Sat, Dec 21, 2019, 8:44 AM Xiang Xiao <xi...@gmail.com> wrote:
> Can we simplify the workflow to avoid creating so many temp branching
> in the official repo:
> 1.User submit PR against the master
> 2.Run style, build and test through CI
> 3.Review and comment PR by committer
> 4.Merge PR into master if all check pass
> User may have to repeat step 1 to 3 several time before PR finally accept.
> Note 1: step 2 may be done by committer manually before the tool is ready.
> Note 2: we can refine how many approvement is required before PR can be
> merge.
> If user send patch to dev@nuttx.apache.org instead, one of committer
> need convert the patch to PR by the same process too.
> If there has a big feature development, committer could create a
> branch for that after voting in dev list, but the same process should
> apply to this branch like master.
> Actually, this process is almost same as bitbucket or github, many
> developer is already familiar with it:
>
> https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
> The major difference from David's is that no any temp PR branch is
> created in the official repo.
>
> Thanks
> Xiang
>
> On Sat, Dec 21, 2019 at 8:36 PM Gregory Nutt <sp...@gmail.com> wrote:
> >
> > This is the mantra we must always follow "support what you users want."
> > Stay focused on the needs and convenience of the end-user. Always good
> > advice. If there are complexities dependencies, we should quantine
> > those complexities and dependencies inside the test architecture. We
> > give the end-user maximal flexibility in all things.
> >
> > Businesses fail that don't listen tho their customers. We will also
> > fail if we do not listen.
> >
> > On 12/21/2019 2:59 AM, Justin Mclean wrote:
> > > Hi,
> > >
> > >> The purpose was accommodating the "repos must be on the ASF
> infrastructure edict"[1] .
> > >> Which I believe, please correct me if I am wrong, is pure git???
> > > Most(?) use git, some also use svn, there might be a couple that still
> use cvs. Use of GitHub is not a requirement, but may be convenient.My
> advice be flexible and support what you users want.
> > >
> > > Thanks,
> > > Justin
> > >
> > >
> >
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Brennan Ashton <ba...@brennanashton.com>.
+1 to this. No ci yet so everything "passes" and just gets the commiter
review. We can define more later as needed
On Sat, Dec 21, 2019, 8:44 AM Xiang Xiao <xi...@gmail.com> wrote:
> Can we simplify the workflow to avoid creating so many temp branching
> in the official repo:
> 1.User submit PR against the master
> 2.Run style, build and test through CI
> 3.Review and comment PR by committer
> 4.Merge PR into master if all check pass
> User may have to repeat step 1 to 3 several time before PR finally accept.
> Note 1: step 2 may be done by committer manually before the tool is ready.
> Note 2: we can refine how many approvement is required before PR can be
> merge.
> If user send patch to dev@nuttx.apache.org instead, one of committer
> need convert the patch to PR by the same process too.
> If there has a big feature development, committer could create a
> branch for that after voting in dev list, but the same process should
> apply to this branch like master.
> Actually, this process is almost same as bitbucket or github, many
> developer is already familiar with it:
>
> https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
> The major difference from David's is that no any temp PR branch is
> created in the official repo.
>
> Thanks
> Xiang
>
> On Sat, Dec 21, 2019 at 8:36 PM Gregory Nutt <sp...@gmail.com> wrote:
> >
> > This is the mantra we must always follow "support what you users want."
> > Stay focused on the needs and convenience of the end-user. Always good
> > advice. If there are complexities dependencies, we should quantine
> > those complexities and dependencies inside the test architecture. We
> > give the end-user maximal flexibility in all things.
> >
> > Businesses fail that don't listen tho their customers. We will also
> > fail if we do not listen.
> >
> > On 12/21/2019 2:59 AM, Justin Mclean wrote:
> > > Hi,
> > >
> > >> The purpose was accommodating the "repos must be on the ASF
> infrastructure edict"[1] .
> > >> Which I believe, please correct me if I am wrong, is pure git???
> > > Most(?) use git, some also use svn, there might be a couple that still
> use cvs. Use of GitHub is not a requirement, but may be convenient.My
> advice be flexible and support what you users want.
> > >
> > > Thanks,
> > > Justin
> > >
> > >
> >
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Xiang Xiao <xi...@gmail.com>.
Can we simplify the workflow to avoid creating so many temp branching
in the official repo:
1.User submit PR against the master
2.Run style, build and test through CI
3.Review and comment PR by committer
4.Merge PR into master if all check pass
User may have to repeat step 1 to 3 several time before PR finally accept.
Note 1: step 2 may be done by committer manually before the tool is ready.
Note 2: we can refine how many approvement is required before PR can be merge.
If user send patch to dev@nuttx.apache.org instead, one of committer
need convert the patch to PR by the same process too.
If there has a big feature development, committer could create a
branch for that after voting in dev list, but the same process should
apply to this branch like master.
Actually, this process is almost same as bitbucket or github, many
developer is already familiar with it:
https://help.github.com/en/github/collaborating-with-issues-and-pull-requests
The major difference from David's is that no any temp PR branch is
created in the official repo.
Thanks
Xiang
On Sat, Dec 21, 2019 at 8:36 PM Gregory Nutt <sp...@gmail.com> wrote:
>
> This is the mantra we must always follow "support what you users want."
> Stay focused on the needs and convenience of the end-user. Always good
> advice. If there are complexities dependencies, we should quantine
> those complexities and dependencies inside the test architecture. We
> give the end-user maximal flexibility in all things.
>
> Businesses fail that don't listen tho their customers. We will also
> fail if we do not listen.
>
> On 12/21/2019 2:59 AM, Justin Mclean wrote:
> > Hi,
> >
> >> The purpose was accommodating the "repos must be on the ASF infrastructure edict"[1] .
> >> Which I believe, please correct me if I am wrong, is pure git???
> > Most(?) use git, some also use svn, there might be a couple that still use cvs. Use of GitHub is not a requirement, but may be convenient.My advice be flexible and support what you users want.
> >
> > Thanks,
> > Justin
> >
> >
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Gregory Nutt <sp...@gmail.com>.
This is the mantra we must always follow "support what you users want."
Stay focused on the needs and convenience of the end-user. Always good
advice. If there are complexities dependencies, we should quantine
those complexities and dependencies inside the test architecture. We
give the end-user maximal flexibility in all things.
Businesses fail that don't listen tho their customers. We will also
fail if we do not listen.
On 12/21/2019 2:59 AM, Justin Mclean wrote:
> Hi,
>
>> The purpose was accommodating the "repos must be on the ASF infrastructure edict"[1] .
>> Which I believe, please correct me if I am wrong, is pure git???
> Most(?) use git, some also use svn, there might be a couple that still use cvs. Use of GitHub is not a requirement, but may be convenient.My advice be flexible and support what you users want.
>
> Thanks,
> Justin
>
>
Re: [CALL for TOP Down workflow Requirements]
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> The purpose was accommodating the "repos must be on the ASF infrastructure edict"[1] .
> Which I believe, please correct me if I am wrong, is pure git???
Most(?) use git, some also use svn, there might be a couple that still use cvs. Use of GitHub is not a requirement, but may be convenient.My advice be flexible and support what you users want.
Thanks,
Justin
Re: [CALL for TOP Down workflow Requirements]
Posted by David Sidrane <da...@apache.org>.
Hi Brennan,
I agree with your reasoning and welcome the change, but let me expand on the initial reasoning. below.
On 2019/12/21 07:56:35, Brennan Ashton <ba...@brennanashton.com> wrote:
> On Fri, Dec 20, 2019, 11:22 PM David Sidrane <da...@apache.org> wrote:
>
> > All,
> >
> > Please help flesh this out.
> >
> > Proposed Workflow Requirements (REQ) and Derived Requirements (DREQ)
> >
> > REQ1) master is branches of apps and nuttx have to always build
> > REQ1.1) ALL development work is done on branches.
> > DREQ1.1.1) master is branch protected prevention pushes to it.
> >
> > REQ2) git bisect shall always be able to build master of the project at
> > every commit.
> > DREQ2.a) merges to master may use squash commits from a PR when
> > atomic commits are needed to insure REC2.
> > DREQ2.b) merges to master may use rebase commits from a PR when NON
> > atomic commits will for insure REC2.
> >
> > REQ3) Submissions shall be PRs against branches typically master. But PR
> > shall be accepted against other branches.
> > (i.e netlink_crypto)
> > REQ3.1) naming conventions shall reflect lineage:
> > REQ3.1.a) naming conventions of branches shall be in the form
> > <root>_<activity>
> > master_pr-add_imxrt20, netlink_crypto-pr-bugfix_AES
> > REQ3.1.b) submissions affecting multiple repos shall use the same
> > branches name on all repos.
> > DREQ3.1.b.1) CI shall test multiple repos by branch name
> >
>
> I would like to loosen up the branch naming requirements, it will make it
> harder for people to contribute little things coming from the "GitHub"
> world, it's not something I see too much outside of the workplace. Also the
> generated branches on GitHub from a PR are using the ids. I'm not trying
> to bring tooling in, but I think we should be aware of this and I think it
> brings minimal gain. I would be more in favor of the title or body of a PR
> doing the linking if we really need the standard to link things together.
> We need to be very sensitive to increases in complexity or we will loose
> new contributors.
>
>
>
> >
> > REQ4) committer may collaborate on branches.
> >
> > REC5) While PR's are preferred, patches may be accepted.
> > DREC5.1) Committers receiving patches shall apply them to a new branch
> > (per REQ3) and open a PR.
> > REC5.1) Committers shall attribute work to the person submitting patch
> >
> > REC6) All PR requires a review.
> > DREC6.1) the project shall publish a list of subject experts
> > REC6.1) Request for review shall be made via email to subject experts or
> > PPMC.
> > REC6.1.1) Multiple reviewers shall be required on OS internals.
> > REC6.1.2) Multiple reviewers may be required on NON OS internals.
> >
> >
> > David
>
>
> The rest sounds good. I would say let's start minimal and work up if we
> find quality or complexity issues.
>
> --Brennan
>
The purpose was accommodating the "repos must be on the ASF infrastructure edict"[1] .
Which I believe, please correct me if I am wrong, is pure git???
Therefore I was removing the dependency of githubs features on the work flow.
The only way I know how to do this in pure git is: by tag, branch name or SHAL
Since we can not use strike out in this environment:
Would you be ok with adding your edits in a diff like form?
I.e.
-REQ3.1) naming conventions shall reflect lineage:
+REQ3.1) naming conventions may reflect lineage:
[1] mentor's email re:50 years support and how the internet changes
Also having to ignore github workfow for the sake of only being top down herein would not be my approach, but I am tying to accommodate everyone input.
David
Re: [CALL for TOP Down workflow Requirements]
Posted by Brennan Ashton <ba...@brennanashton.com>.
On Fri, Dec 20, 2019, 11:22 PM David Sidrane <da...@apache.org> wrote:
> All,
>
> Please help flesh this out.
>
> Proposed Workflow Requirements (REQ) and Derived Requirements (DREQ)
>
> REQ1) master is branches of apps and nuttx have to always build
> REQ1.1) ALL development work is done on branches.
> DREQ1.1.1) master is branch protected prevention pushes to it.
>
> REQ2) git bisect shall always be able to build master of the project at
> every commit.
> DREQ2.a) merges to master may use squash commits from a PR when
> atomic commits are needed to insure REC2.
> DREQ2.b) merges to master may use rebase commits from a PR when NON
> atomic commits will for insure REC2.
>
> REQ3) Submissions shall be PRs against branches typically master. But PR
> shall be accepted against other branches.
> (i.e netlink_crypto)
> REQ3.1) naming conventions shall reflect lineage:
> REQ3.1.a) naming conventions of branches shall be in the form
> <root>_<activity>
> master_pr-add_imxrt20, netlink_crypto-pr-bugfix_AES
> REQ3.1.b) submissions affecting multiple repos shall use the same
> branches name on all repos.
> DREQ3.1.b.1) CI shall test multiple repos by branch name
>
I would like to loosen up the branch naming requirements, it will make it
harder for people to contribute little things coming from the "GitHub"
world, it's not something I see too much outside of the workplace. Also the
generated branches on GitHub from a PR are using the ids. I'm not trying
to bring tooling in, but I think we should be aware of this and I think it
brings minimal gain. I would be more in favor of the title or body of a PR
doing the linking if we really need the standard to link things together.
We need to be very sensitive to increases in complexity or we will loose
new contributors.
>
> REQ4) committer may collaborate on branches.
>
> REC5) While PR's are preferred, patches may be accepted.
> DREC5.1) Committers receiving patches shall apply them to a new branch
> (per REQ3) and open a PR.
> REC5.1) Committers shall attribute work to the person submitting patch
>
> REC6) All PR requires a review.
> DREC6.1) the project shall publish a list of subject experts
> REC6.1) Request for review shall be made via email to subject experts or
> PPMC.
> REC6.1.1) Multiple reviewers shall be required on OS internals.
> REC6.1.2) Multiple reviewers may be required on NON OS internals.
>
>
> David
The rest sounds good. I would say let's start minimal and work up if we
find quality or complexity issues.
--Brennan