Date   
Re: Registry Refactor design approved, where do we put it?

Cloud Tsai
 

Hi all,

If we put ADR in one repository, why not using edgex-docs?
edgex-docs is for document purpose and across different working groups, including QA and DevOps.
If we put ADR in edgex-go, it needs to run all the validations (unit test, code analysis, and blackbox test potentially) for each PR creation and changes.


On Tue, 10 Dec 2019 at 05:33, Malini Bhandaru via Lists.Edgexfoundry.Org <mbhandaru=vmware.com@...> wrote:

+1  Lenny and Tingyu’s points.  Add links to the ARDs in the PRs.

 

From: <EdgeX-TSC-Core@...> on behalf of "Goodell, Leonard via Lists.Edgexfoundry.Org" <leonard.goodell=intel.com@...>
Reply to: "leonard.goodell@..." <leonard.goodell@...>
Date: Monday, 9 December 2019 at 7:35 AM
To: "EdgeX-TSC-Core@..." <EdgeX-TSC-Core@...>
Cc: "EdgeX-TSC-Core@..." <EdgeX-TSC-Core@...>
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

I agree with Michael that it is really about documenting and not much about process. The only process needed is defining the document format to use and where/how to store them.

 

I also agree with Tingu about storing the documents close to the code. I suggest edgex-core be the main storage for all core and cross-cutting designs and domain specific designs be stored in the repos containing the implementations.

 

I like the idea of "encouraged but not required" for now as long as we address format and storage for consistency.

 

-Lenny

 

From: Tingyu.Zeng@... <Tingyu.Zeng@...>
Sent: Monday, December 09, 2019 7:48 AM
To: jim@...; M.Estrin@...
Cc: Trevor.Conn@...; Goodell, Leonard <leonard.goodell@...>; EdgeX-TSC-Core@...
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

I see the benefit of having ARDs sitting next to the individual repo - it is highly visible and may force the authors/owners to update the ADR whenever some fundamental change.  As past experience shows it is always painful to keep the document ( such as wiki) up to date since they are separated from the codebase. Even if we are unable to have agreement to enforce ARD at this stage I see more benefit of it encouraged and adopted whenever possible. 

 

 

Thanks,

Tingyu

 


From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Monday, December 9, 2019 9:29 AM
To: Estrin, Michael
Cc: Conn, Trevor; Goodell, Leonard;
🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Thanks Michael.  Other thoughts?

 

Again, no agenda or strong opinion on my part, but even if we do it as an "encouraged but not required" type of thing, I would think that we'd want to try to align on a tool or process of some sort to make it easier to move to as a group when/if we do travel this path.

 

j

 

 

On Mon, 9 Dec 2019 at 08:35, <M.Estrin@...> wrote:

Having proposed architecture decision records (ADRs), I'm biased.  I also acknowledge I wasn't in the room when ADRs were discussed on the fourth day of the F2F; I was busy helping security sort their blackbox testing issues.

 

Even though ADRs were "rejected," I don't understand why we would discourage anyone who wants to from using them as a means to document architectural decisions.  I'm ecstatic that Lenny picked up the concept and ran with it for describing how registry and configuration are to be separated.

 

I don't see any "process" concerns here.  It's a method for documenting decisions.  Although we used Lenny's ADR to facilitate discussion, there's no process required or implied by an ADR.  He could have easily substituted one or more documents/diagrams of different types to do the same thing.

 

Since most architectural decisions are likely to apply to more than one working group's repositories, I'd propose the creation of a separate repository to hold them.  The alternative is to break ADRs across repositories (which makes them harder to find) or to include them all in core (which would end up holding documents that aren't directly related to or implemented by core).  Further, I'd suggest a file naming convention (date and title; e.g. 20091207_Some_Title_Goes_Here) and an index file that provides links (and potentially brief abstracts) of each for quick reference/referral. 

 

Michael W. Estrin

Software System Senior Principal Engineer

Dell Technologies | IoT Solutions Division | IoT Platform Development Team

mobile: +1 512 762 9978

m.estrin@...

 

 


From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Sunday, December 8, 2019 2:00 PM
To: Conn, Trevor
Cc: Goodell, Leonard;
🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

 

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.


Jim White

CTO, IOTech

EdgeX Foundry co-founder & TSC Vice-chairman

On EdgeX Slack @ jpwhite

612-916-6693

 

 

On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 



--
Best Regards,
Cloud Tsai

Re: Registry Refactor design approved, where do we put it?

Malini Bhandaru
 

+1  Lenny and Tingyu’s points.  Add links to the ARDs in the PRs.

 

From: <EdgeX-TSC-Core@...> on behalf of "Goodell, Leonard via Lists.Edgexfoundry.Org" <leonard.goodell=intel.com@...>
Reply to: "leonard.goodell@..." <leonard.goodell@...>
Date: Monday, 9 December 2019 at 7:35 AM
To: "EdgeX-TSC-Core@..." <EdgeX-TSC-Core@...>
Cc: "EdgeX-TSC-Core@..." <EdgeX-TSC-Core@...>
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

I agree with Michael that it is really about documenting and not much about process. The only process needed is defining the document format to use and where/how to store them.

 

I also agree with Tingu about storing the documents close to the code. I suggest edgex-core be the main storage for all core and cross-cutting designs and domain specific designs be stored in the repos containing the implementations.

 

I like the idea of "encouraged but not required" for now as long as we address format and storage for consistency.

 

-Lenny

 

From: Tingyu.Zeng@... <Tingyu.Zeng@...>
Sent: Monday, December 09, 2019 7:48 AM
To: jim@...; M.Estrin@...
Cc: Trevor.Conn@...; Goodell, Leonard <leonard.goodell@...>; EdgeX-TSC-Core@...
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

I see the benefit of having ARDs sitting next to the individual repo - it is highly visible and may force the authors/owners to update the ADR whenever some fundamental change.  As past experience shows it is always painful to keep the document ( such as wiki) up to date since they are separated from the codebase. Even if we are unable to have agreement to enforce ARD at this stage I see more benefit of it encouraged and adopted whenever possible. 

 

 

Thanks,

Tingyu

 


From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Monday, December 9, 2019 9:29 AM
To: Estrin, Michael
Cc: Conn, Trevor; Goodell, Leonard;
🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Thanks Michael.  Other thoughts?

 

Again, no agenda or strong opinion on my part, but even if we do it as an "encouraged but not required" type of thing, I would think that we'd want to try to align on a tool or process of some sort to make it easier to move to as a group when/if we do travel this path.

 

j

 

 

On Mon, 9 Dec 2019 at 08:35, <M.Estrin@...> wrote:

Having proposed architecture decision records (ADRs), I'm biased.  I also acknowledge I wasn't in the room when ADRs were discussed on the fourth day of the F2F; I was busy helping security sort their blackbox testing issues.

 

Even though ADRs were "rejected," I don't understand why we would discourage anyone who wants to from using them as a means to document architectural decisions.  I'm ecstatic that Lenny picked up the concept and ran with it for describing how registry and configuration are to be separated.

 

I don't see any "process" concerns here.  It's a method for documenting decisions.  Although we used Lenny's ADR to facilitate discussion, there's no process required or implied by an ADR.  He could have easily substituted one or more documents/diagrams of different types to do the same thing.

 

Since most architectural decisions are likely to apply to more than one working group's repositories, I'd propose the creation of a separate repository to hold them.  The alternative is to break ADRs across repositories (which makes them harder to find) or to include them all in core (which would end up holding documents that aren't directly related to or implemented by core).  Further, I'd suggest a file naming convention (date and title; e.g. 20091207_Some_Title_Goes_Here) and an index file that provides links (and potentially brief abstracts) of each for quick reference/referral. 

 

Michael W. Estrin

Software System Senior Principal Engineer

Dell Technologies | IoT Solutions Division | IoT Platform Development Team

mobile: +1 512 762 9978

m.estrin@...

 

 


From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Sunday, December 8, 2019 2:00 PM
To: Conn, Trevor
Cc: Goodell, Leonard;
🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

 

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.


Jim White

CTO, IOTech

EdgeX Foundry co-founder & TSC Vice-chairman

On EdgeX Slack @ jpwhite

612-916-6693

 

 

On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Registry Refactor design approved, where do we put it?

Goodell, Leonard
 

I agree with Michael that it is really about documenting and not much about process. The only process needed is defining the document format to use and where/how to store them.

 

I also agree with Tingu about storing the documents close to the code. I suggest edgex-core be the main storage for all core and cross-cutting designs and domain specific designs be stored in the repos containing the implementations.

 

I like the idea of "encouraged but not required" for now as long as we address format and storage for consistency.

 

-Lenny

 

From: Tingyu.Zeng@... <Tingyu.Zeng@...>
Sent: Monday, December 09, 2019 7:48 AM
To: jim@...; M.Estrin@...
Cc: Trevor.Conn@...; Goodell, Leonard <leonard.goodell@...>; EdgeX-TSC-Core@...
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

I see the benefit of having ARDs sitting next to the individual repo - it is highly visible and may force the authors/owners to update the ADR whenever some fundamental change.  As past experience shows it is always painful to keep the document ( such as wiki) up to date since they are separated from the codebase. Even if we are unable to have agreement to enforce ARD at this stage I see more benefit of it encouraged and adopted whenever possible. 

 

 

Thanks,

Tingyu

 


From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Monday, December 9, 2019 9:29 AM
To: Estrin, Michael
Cc: Conn, Trevor; Goodell, Leonard;
🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Thanks Michael.  Other thoughts?

 

Again, no agenda or strong opinion on my part, but even if we do it as an "encouraged but not required" type of thing, I would think that we'd want to try to align on a tool or process of some sort to make it easier to move to as a group when/if we do travel this path.

 

j

 

 

On Mon, 9 Dec 2019 at 08:35, <M.Estrin@...> wrote:

Having proposed architecture decision records (ADRs), I'm biased.  I also acknowledge I wasn't in the room when ADRs were discussed on the fourth day of the F2F; I was busy helping security sort their blackbox testing issues.

 

Even though ADRs were "rejected," I don't understand why we would discourage anyone who wants to from using them as a means to document architectural decisions.  I'm ecstatic that Lenny picked up the concept and ran with it for describing how registry and configuration are to be separated.

 

I don't see any "process" concerns here.  It's a method for documenting decisions.  Although we used Lenny's ADR to facilitate discussion, there's no process required or implied by an ADR.  He could have easily substituted one or more documents/diagrams of different types to do the same thing.

 

Since most architectural decisions are likely to apply to more than one working group's repositories, I'd propose the creation of a separate repository to hold them.  The alternative is to break ADRs across repositories (which makes them harder to find) or to include them all in core (which would end up holding documents that aren't directly related to or implemented by core).  Further, I'd suggest a file naming convention (date and title; e.g. 20091207_Some_Title_Goes_Here) and an index file that provides links (and potentially brief abstracts) of each for quick reference/referral. 

 

Michael W. Estrin

Software System Senior Principal Engineer

Dell Technologies | IoT Solutions Division | IoT Platform Development Team

mobile: +1 512 762 9978

m.estrin@...

 

 


From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Sunday, December 8, 2019 2:00 PM
To: Conn, Trevor
Cc: Goodell, Leonard;
🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

 

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.


Jim White

CTO, IOTech

EdgeX Foundry co-founder & TSC Vice-chairman

On EdgeX Slack @ jpwhite

612-916-6693

 

 

On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Registry Refactor design approved, where do we put it?

Zeng, Tingyu
 

I see the benefit of having ARDs sitting next to the individual repo - it is highly visible and may force the authors/owners to update the ADR whenever some fundamental change.  As past experience shows it is always painful to keep the document ( such as wiki) up to date since they are separated from the codebase. Even if we are unable to have agreement to enforce ARD at this stage I see more benefit of it encouraged and adopted whenever possible. 



Thanks,

Tingyu



From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Monday, December 9, 2019 9:29 AM
To: Estrin, Michael
Cc: Conn, Trevor; Goodell, Leonard; 🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?
 

[EXTERNAL EMAIL]

Thanks Michael.  Other thoughts?

Again, no agenda or strong opinion on my part, but even if we do it as an "encouraged but not required" type of thing, I would think that we'd want to try to align on a tool or process of some sort to make it easier to move to as a group when/if we do travel this path.

j


On Mon, 9 Dec 2019 at 08:35, <M.Estrin@...> wrote:

Having proposed architecture decision records (ADRs), I'm biased.  I also acknowledge I wasn't in the room when ADRs were discussed on the fourth day of the F2F; I was busy helping security sort their blackbox testing issues.


Even though ADRs were "rejected," I don't understand why we would discourage anyone who wants to from using them as a means to document architectural decisions.  I'm ecstatic that Lenny picked up the concept and ran with it for describing how registry and configuration are to be separated.


I don't see any "process" concerns here.  It's a method for documenting decisions.  Although we used Lenny's ADR to facilitate discussion, there's no process required or implied by an ADR.  He could have easily substituted one or more documents/diagrams of different types to do the same thing.


Since most architectural decisions are likely to apply to more than one working group's repositories, I'd propose the creation of a separate repository to hold them.  The alternative is to break ADRs across repositories (which makes them harder to find) or to include them all in core (which would end up holding documents that aren't directly related to or implemented by core).  Further, I'd suggest a file naming convention (date and title; e.g. 20091207_Some_Title_Goes_Here) and an index file that provides links (and potentially brief abstracts) of each for quick reference/referral. 


Michael W. Estrin

Software System Senior Principal Engineer

Dell Technologies | IoT Solutions Division | IoT Platform Development Team

mobile: +1 512 762 9978

m.estrin@...




From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Sunday, December 8, 2019 2:00 PM
To: Conn, Trevor
Cc: Goodell, Leonard; 🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?
 

[EXTERNAL EMAIL]

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.

Jim White
CTO, IOTech
EdgeX Foundry co-founder & TSC Vice-chairman
On EdgeX Slack @ jpwhite
612-916-6693


On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Registry Refactor design approved, where do we put it?

Michael Estrin
 

Strongly discourage wrapping ADRs in process.  It's a document format.  To that end, a minimalist approach would be to define an ADR skeleton (I previously proposed we follow https://github.com/joelparkerhenderson/architecture_decision_record/blob/master/adr_template_by_michael_nygard.md), form (markup is typically used), and storage (suggested in my prior message).




From: Jim White <jim@...>
Sent: Monday, December 9, 2019 8:29 AM
To: Estrin, Michael
Cc: Conn, Trevor; Goodell, Leonard; 🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?
 

[EXTERNAL EMAIL]

Thanks Michael.  Other thoughts?

Again, no agenda or strong opinion on my part, but even if we do it as an "encouraged but not required" type of thing, I would think that we'd want to try to align on a tool or process of some sort to make it easier to move to as a group when/if we do travel this path.

j


On Mon, 9 Dec 2019 at 08:35, <M.Estrin@...> wrote:

Having proposed architecture decision records (ADRs), I'm biased.  I also acknowledge I wasn't in the room when ADRs were discussed on the fourth day of the F2F; I was busy helping security sort their blackbox testing issues.


Even though ADRs were "rejected," I don't understand why we would discourage anyone who wants to from using them as a means to document architectural decisions.  I'm ecstatic that Lenny picked up the concept and ran with it for describing how registry and configuration are to be separated.


I don't see any "process" concerns here.  It's a method for documenting decisions.  Although we used Lenny's ADR to facilitate discussion, there's no process required or implied by an ADR.  He could have easily substituted one or more documents/diagrams of different types to do the same thing.


Since most architectural decisions are likely to apply to more than one working group's repositories, I'd propose the creation of a separate repository to hold them.  The alternative is to break ADRs across repositories (which makes them harder to find) or to include them all in core (which would end up holding documents that aren't directly related to or implemented by core).  Further, I'd suggest a file naming convention (date and title; e.g. 20091207_Some_Title_Goes_Here) and an index file that provides links (and potentially brief abstracts) of each for quick reference/referral. 


Michael W. Estrin

Software System Senior Principal Engineer

Dell Technologies | IoT Solutions Division | IoT Platform Development Team

mobile: +1 512 762 9978

m.estrin@...




From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Sunday, December 8, 2019 2:00 PM
To: Conn, Trevor
Cc: Goodell, Leonard; 🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?
 

[EXTERNAL EMAIL]

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.

Jim White
CTO, IOTech
EdgeX Foundry co-founder & TSC Vice-chairman
On EdgeX Slack @ jpwhite
612-916-6693


On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Registry Refactor design approved, where do we put it?

Jim White
 

Thanks Michael.  Other thoughts?

Again, no agenda or strong opinion on my part, but even if we do it as an "encouraged but not required" type of thing, I would think that we'd want to try to align on a tool or process of some sort to make it easier to move to as a group when/if we do travel this path.

j


On Mon, 9 Dec 2019 at 08:35, <M.Estrin@...> wrote:

Having proposed architecture decision records (ADRs), I'm biased.  I also acknowledge I wasn't in the room when ADRs were discussed on the fourth day of the F2F; I was busy helping security sort their blackbox testing issues.


Even though ADRs were "rejected," I don't understand why we would discourage anyone who wants to from using them as a means to document architectural decisions.  I'm ecstatic that Lenny picked up the concept and ran with it for describing how registry and configuration are to be separated.


I don't see any "process" concerns here.  It's a method for documenting decisions.  Although we used Lenny's ADR to facilitate discussion, there's no process required or implied by an ADR.  He could have easily substituted one or more documents/diagrams of different types to do the same thing.


Since most architectural decisions are likely to apply to more than one working group's repositories, I'd propose the creation of a separate repository to hold them.  The alternative is to break ADRs across repositories (which makes them harder to find) or to include them all in core (which would end up holding documents that aren't directly related to or implemented by core).  Further, I'd suggest a file naming convention (date and title; e.g. 20091207_Some_Title_Goes_Here) and an index file that provides links (and potentially brief abstracts) of each for quick reference/referral. 


Michael W. Estrin

Software System Senior Principal Engineer

Dell Technologies | IoT Solutions Division | IoT Platform Development Team

mobile: +1 512 762 9978

m.estrin@...




From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Sunday, December 8, 2019 2:00 PM
To: Conn, Trevor
Cc: Goodell, Leonard; 🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?
 

[EXTERNAL EMAIL]

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.

Jim White
CTO, IOTech
EdgeX Foundry co-founder & TSC Vice-chairman
On EdgeX Slack @ jpwhite
612-916-6693


On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Registry Refactor design approved, where do we put it?

Michael Estrin
 

​Having proposed architecture decision records (ADRs), I'm biased.  I also acknowledge I wasn't in the room when ADRs were discussed on the fourth day of the F2F; I was busy helping security sort their blackbox testing issues.


Even though ADRs were "rejected," I don't understand why we would discourage anyone who wants to from using them as a means to document architectural decisions.  I'm ecstatic that Lenny picked up the concept and ran with it for describing how registry and configuration are to be separated.


I don't see any "process" concerns here.  It's a method for documenting decisions.  Although we used Lenny's ADR to facilitate discussion, there's no process required or implied by an ADR.  He could have easily substituted one or more documents/diagrams of different types to do the same thing.


Since most architectural decisions are likely to apply to more than one working group's repositories, I'd propose the creation of a separate repository to hold them.  The alternative is to break ADRs across repositories (which makes them harder to find) or to include them all in core (which would end up holding documents that aren't directly related to or implemented by core).  Further, I'd suggest a file naming convention (date and title; e.g. 20091207_Some_Title_Goes_Here) and an index file that provides links (and potentially brief abstracts) of each for quick reference/referral. 


Michael W. Estrin

Software System Senior Principal Engineer

Dell Technologies | IoT Solutions Division | IoT Platform Development Team

mobile: +1 512 762 9978

m.estrin@...




From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Jim White <jim@...>
Sent: Sunday, December 8, 2019 2:00 PM
To: Conn, Trevor
Cc: Goodell, Leonard; 🐙 Core WG
Subject: Re: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?
 

[EXTERNAL EMAIL]

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.

Jim White
CTO, IOTech
EdgeX Foundry co-founder & TSC Vice-chairman
On EdgeX Slack @ jpwhite
612-916-6693


On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Registry Refactor design approved, where do we put it?

Jim White
 

I think we talked about it, but it was rejected for now (listen to discussion on recording at 2:03:00 here https://zoom.us/recording/share/azOc86-S9PtS4vjGE5vgBVS1oqQE5hDkQBT0B043nhWwIumekTziMw).  I think the sentiments of  many was that perhaps we do this in the future, but comments from Tony and others was that we have too much change for this release to also worry about going the route of formal ADR yet.

I stand neutral on it - so I'd welcome feedback from other WG leads and architect before we adopt.  I'll add it to TSC topics this week to try to get other inputs.  Welcome others to chime in on this thread if they have opinions.

Jim White
CTO, IOTech
EdgeX Foundry co-founder & TSC Vice-chairman
On EdgeX Slack @ jpwhite
612-916-6693


On Sat, 7 Dec 2019 at 16:47, <Trevor.Conn@...> wrote:

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Registry Refactor design approved, where do we put it?

Trevor.Conn@...
 

I’m in favor of it, Lenny. However adding the “/adr” directory commits us to a certain methodology. I’d hate to add that directory just for one document. Given that the reaction to how you packaged this proposal has been very positive, it supports the case that we should be using ADRs to formally capture how the architecture is changing to support our feature roadmap. Some other features that come to mind in this regard are Geneva API 2.0 changes and Dynamic Device Discovery.

 

I realize there’s some overhead involved in the ADR process, but the benefits do seem to be obvious in both facilitating discussion and then capturing the outcome.

So +1 from me.

 

Trevor

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Friday, December 6, 2019 4:01 PM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Registry Refactor design approved, where do we put it?

 

[EXTERNAL EMAIL]

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Registry Refactor design approved, where do we put it?

Goodell, Leonard
 

Now that the Registry Refactor design has been approved, we need to agree where these documents should reside.

 

For the below PR I created an “adr” (architecture decision records) folder in edgex-go

https://github.com/edgexfoundry/edgex-go/pull/2133

 

Since we talked about ADRs in the PHX F2F, I thought this would be a good place to start.

 

Thoughts?

 

-Lenny

 

 

Re: Approval request to create new go-mod-configuration repo in holding

Jim White
 

the intent was that any TSC member could request and be granted a holding repo without any help from others.  So Trevor could request a repo in holding and not need a 2nd.  Lenny would need a TSC member approval, but just one.

This is our policy and so LF just is making sure we are following are own rules.  But it sounds like we need to clarify the language if we have questions about this ourselves.

Jim White
CTO, IOTech
EdgeX Foundry co-founder & TSC Vice-chairman
On EdgeX Slack @ jpwhite
612-916-6693


On Thu, 5 Dec 2019 at 10:11, Goodell, Leonard <leonard.goodell@...> wrote:

I don’t think so. I think it means 1 TSC approver beyond the requester…

 

From: Rodney Hess <rodney@...>
Sent: Thursday, December 05, 2019 9:32 AM
To: Goodell, Leonard <leonard.goodell@...>
Cc: 🐙 Core WG <EdgeX-TSC-Core@...>
Subject: Re: [Edgex-tsc-core] Approval request to create new go-mod-configuration repo in holding

 

Can someone clarify, if a TSC member makes the request, does that meet the “approval from any single TSC member”?

 

~Rodney



On Dec 5, 2019, at 11:29, Goodell, Leonard <leonard.goodell@...> wrote:

 

For the new Registry refactoring we need to create the new go-mod-configuration repo in holding.

 

Our process requires approval from any single TSC member.

 

Thanks!

   Lenny

 

 

Re: Approval request to create new go-mod-configuration repo in holding

Goodell, Leonard
 

I don’t think so. I think it means 1 TSC approver beyond the requester…

 

From: Rodney Hess <rodney@...>
Sent: Thursday, December 05, 2019 9:32 AM
To: Goodell, Leonard <leonard.goodell@...>
Cc: 🐙 Core WG <EdgeX-TSC-Core@...>
Subject: Re: [Edgex-tsc-core] Approval request to create new go-mod-configuration repo in holding

 

Can someone clarify, if a TSC member makes the request, does that meet the “approval from any single TSC member”?

 

~Rodney



On Dec 5, 2019, at 11:29, Goodell, Leonard <leonard.goodell@...> wrote:

 

For the new Registry refactoring we need to create the new go-mod-configuration repo in holding.

 

Our process requires approval from any single TSC member.

 

Thanks!

   Lenny

 

 

Re: Approval request to create new go-mod-configuration repo in holding

Trevor.Conn@...
 

+1 approved

 

From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> On Behalf Of Goodell, Leonard
Sent: Thursday, December 5, 2019 10:30 AM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Approval request to create new go-mod-configuration repo in holding

 

[EXTERNAL EMAIL]

For the new Registry refactoring we need to create the new go-mod-configuration repo in holding.

 

Our process requires approval from any single TSC member.

 

Thanks!

   Lenny

 

Re: Approval request to create new go-mod-configuration repo in holding

Rodney
 

Can someone clarify, if a TSC member makes the request, does that meet the “approval from any single TSC member”?

~Rodney

On Dec 5, 2019, at 11:29, Goodell, Leonard <leonard.goodell@...> wrote:

For the new Registry refactoring we need to create the new go-mod-configuration repo in holding.
 
Our process requires approval from any single TSC member.
 
Thanks!
   Lenny
 

Re: Approval request to create new go-mod-configuration repo in holding

Michael Estrin
 

​+1


From: EdgeX-TSC-Core@... <EdgeX-TSC-Core@...> on behalf of Goodell, Leonard <leonard.goodell@...>
Sent: Thursday, December 5, 2019 10:29 AM
To: EdgeX-TSC-Core@...
Subject: [Edgex-tsc-core] Approval request to create new go-mod-configuration repo in holding
 

[EXTERNAL EMAIL]

For the new Registry refactoring we need to create the new go-mod-configuration repo in holding.

 

Our process requires approval from any single TSC member.

 

Thanks!

   Lenny

 

Approval request to create new go-mod-configuration repo in holding

Goodell, Leonard
 

For the new Registry refactoring we need to create the new go-mod-configuration repo in holding.

 

Our process requires approval from any single TSC member.

 

Thanks!

   Lenny

 

Upcoming Event: EdgeX Core WG Meeting (Weekly) - Thu, 12/05/2019 8:00am-9:00am, Please RSVP #cal-reminder

EdgeX-TSC-Core@lists.edgexfoundry.org Calendar <EdgeX-TSC-Core@...>
 

Reminder: EdgeX Core WG Meeting (Weekly)

When: Thursday, 5 December 2019, 8:00am to 9:00am, (GMT-08:00) America/Los Angeles

Where:https://zoom.us/j/201883906

An RSVP is requested. Click here to RSVP

Organizer: EdgeX-TSC-Core@...

Description: EdgeX Core WG Meeting. Meeting content posted to Core WG Wiki.
Meeting Lead: Trevor Conn, Core WG Chair, trevor_conn@...
-----
Join from PC, Mac, Linux, iOS or Android: https://zoom.us/j/201883906

Or iPhone one-tap (US Toll): +16468769923,,201883906# or +16699006833,,201883906#

Or Telephone:
    Dial: +1 646 876 9923 (US Toll) or +1 669 900 6833 (US Toll)
    +1 877 369 0926 (US Toll Free)
    +1 877 853 5247 (US Toll Free)
    Meeting ID: 201 883 906
    International numbers available: https://zoom.us/zoomconference?m=Qqq7sz4L88ze6B1M1tTIMQkO-eZL20cy

Re: [Edgex-tsc-device-services] Swagger API document development process

Gregg, James R <james.r.gregg@...>
 

Thank you Cloud. Sounds like a good plan and appreciate the heads up. 


On Nov 27, 2019, at 5:56 PM, Cloud Tsai <cloud@...> wrote:


Hi James,

Yes, we will open an issue, and this mail is just a heads up.
Once we confirm the approach, I will write down more information for explanation, but DevOps meeting is too late to me (1:00 AM).
We will open the issue and even the PR, and we just need your team to review.  Basically, once we switch RAML to Swagger, we need to modify the API document generation job.  I assume it happens automatically now.

On Thu, 28 Nov 2019 at 08:48, Gregg, James R <james.r.gregg@...> wrote:
Cloud, 
Would you like to write up the help needed and submit an issue to ci-management rep?   That way DevOps can assess the work involved.  I’m not clear what help is needed  from DevOps per this email.  We may want to ask you or a rep to come into the next DevOps WG meeting. 
Our scope for Geneva is set for the Jenkins Pipeline transformation, but if we have bandwidth and this is a priority that enables the project we can try to pull in this additional scope. 

Thanks. 

James Gregg

Thank you. 


On Nov 27, 2019, at 3:49 PM, Cloud Tsai <cloud@...> wrote:


Hi all,

As promised last week, we have found out some alternative ways to generate API documents from the swagger files on GitHub.
If you didn't join the QA Working Group meeting this week, you can listen to the recording in 11:17 ~ 18:28.  My colleague, Andrew Foster, explained the ways we found out.
https://zoom.us/recording/share/sXM4tUWvQUKLoO2DTlr3Z_NNDJoocXgBmRXlaOyKrUawIumekTziMw

Due to the limitation, we can't sync swagger file from GitHub to SwaggerHub or vice versa.  SwaggerHub misses the signoff feature to commit changes, so it will never pass our DCO.

There is a command line tool called swagger-codegen, and it can generate html from swagger (core-command sample attached) as what we did using raml2html currently.  We can leverage it to generate HTML file on Jenkins and push to our document website.  Here is our current API page with RAML:

However, we just found another better way.   There is an online API on SwaggerHub, and we verify it works fine.  Please see the attached slide we summarized, and the API sample is on page 3.  After PR merged, we can push the swagger file to SwaggerHub automatically via Jenkins jobs instead of generate HTML and put the SwaggerHub document link on our document web site, like this:
We need DevOps team's support on this part.

As a result, the process will be:
  1. Use any of your favorite swagger editor, such as https://editor.swagger.io/ to create or modify the API definition.  Note that we should all use the latest version openapi: 3.0.1, not swagger 2.0.
  2. Commit the file onto GitHub.
  3. GitHub PR merge trigger the Jenkins job.
  4. The Jenkins job determines whether the API documents are modified, if yes, post to SwaggerHub API according to the version.
Please let me know if you have any question or advice.  Thanks.

--
Best Regards,
Cloud Tsai
<Swagger update.pdf>
<core-command.zip>


--
Best Regards,
Cloud Tsai

Re: [Edgex-tsc-device-services] Swagger API document development process

Gregg, James R <james.r.gregg@...>
 

Cloud, 
Would you like to write up the help needed and submit an issue to ci-management rep?   That way DevOps can assess the work involved.  I’m not clear what help is needed  from DevOps per this email.  We may want to ask you or a rep to come into the next DevOps WG meeting. 
Our scope for Geneva is set for the Jenkins Pipeline transformation, but if we have bandwidth and this is a priority that enables the project we can try to pull in this additional scope. 

Thanks. 

James Gregg

Thank you. 


On Nov 27, 2019, at 3:49 PM, Cloud Tsai <cloud@...> wrote:


Hi all,

As promised last week, we have found out some alternative ways to generate API documents from the swagger files on GitHub.
If you didn't join the QA Working Group meeting this week, you can listen to the recording in 11:17 ~ 18:28.  My colleague, Andrew Foster, explained the ways we found out.
https://zoom.us/recording/share/sXM4tUWvQUKLoO2DTlr3Z_NNDJoocXgBmRXlaOyKrUawIumekTziMw

Due to the limitation, we can't sync swagger file from GitHub to SwaggerHub or vice versa.  SwaggerHub misses the signoff feature to commit changes, so it will never pass our DCO.

There is a command line tool called swagger-codegen, and it can generate html from swagger (core-command sample attached) as what we did using raml2html currently.  We can leverage it to generate HTML file on Jenkins and push to our document website.  Here is our current API page with RAML:

However, we just found another better way.   There is an online API on SwaggerHub, and we verify it works fine.  Please see the attached slide we summarized, and the API sample is on page 3.  After PR merged, we can push the swagger file to SwaggerHub automatically via Jenkins jobs instead of generate HTML and put the SwaggerHub document link on our document web site, like this:
We need DevOps team's support on this part.

As a result, the process will be:
  1. Use any of your favorite swagger editor, such as https://editor.swagger.io/ to create or modify the API definition.  Note that we should all use the latest version openapi: 3.0.1, not swagger 2.0.
  2. Commit the file onto GitHub.
  3. GitHub PR merge trigger the Jenkins job.
  4. The Jenkins job determines whether the API documents are modified, if yes, post to SwaggerHub API according to the version.
Please let me know if you have any question or advice.  Thanks.

--
Best Regards,
Cloud Tsai
<Swagger update.pdf>
<core-command.zip>

Re: [Edgex-tsc-device-services] Swagger API document development process

Cloud Tsai
 

Hi James,

Yes, we will open an issue, and this mail is just a heads up.
Once we confirm the approach, I will write down more information for explanation, but DevOps meeting is too late to me (1:00 AM).
We will open the issue and even the PR, and we just need your team to review.  Basically, once we switch RAML to Swagger, we need to modify the API document generation job.  I assume it happens automatically now.

On Thu, 28 Nov 2019 at 08:48, Gregg, James R <james.r.gregg@...> wrote:
Cloud, 
Would you like to write up the help needed and submit an issue to ci-management rep?   That way DevOps can assess the work involved.  I’m not clear what help is needed  from DevOps per this email.  We may want to ask you or a rep to come into the next DevOps WG meeting. 
Our scope for Geneva is set for the Jenkins Pipeline transformation, but if we have bandwidth and this is a priority that enables the project we can try to pull in this additional scope. 

Thanks. 

James Gregg

Thank you. 


On Nov 27, 2019, at 3:49 PM, Cloud Tsai <cloud@...> wrote:


Hi all,

As promised last week, we have found out some alternative ways to generate API documents from the swagger files on GitHub.
If you didn't join the QA Working Group meeting this week, you can listen to the recording in 11:17 ~ 18:28.  My colleague, Andrew Foster, explained the ways we found out.
https://zoom.us/recording/share/sXM4tUWvQUKLoO2DTlr3Z_NNDJoocXgBmRXlaOyKrUawIumekTziMw

Due to the limitation, we can't sync swagger file from GitHub to SwaggerHub or vice versa.  SwaggerHub misses the signoff feature to commit changes, so it will never pass our DCO.

There is a command line tool called swagger-codegen, and it can generate html from swagger (core-command sample attached) as what we did using raml2html currently.  We can leverage it to generate HTML file on Jenkins and push to our document website.  Here is our current API page with RAML:

However, we just found another better way.   There is an online API on SwaggerHub, and we verify it works fine.  Please see the attached slide we summarized, and the API sample is on page 3.  After PR merged, we can push the swagger file to SwaggerHub automatically via Jenkins jobs instead of generate HTML and put the SwaggerHub document link on our document web site, like this:
We need DevOps team's support on this part.

As a result, the process will be:
  1. Use any of your favorite swagger editor, such as https://editor.swagger.io/ to create or modify the API definition.  Note that we should all use the latest version openapi: 3.0.1, not swagger 2.0.
  2. Commit the file onto GitHub.
  3. GitHub PR merge trigger the Jenkins job.
  4. The Jenkins job determines whether the API documents are modified, if yes, post to SwaggerHub API according to the version.
Please let me know if you have any question or advice.  Thanks.

--
Best Regards,
Cloud Tsai
<Swagger update.pdf>
<core-command.zip>


--
Best Regards,
Cloud Tsai