Subject: [Tools-arch] Recommendation 10: One-stop shop tool

From: Jay Daley <[email-masked]>
Date: Fri, 9 Apr 2021 13:13:22 +1200

=  Recommendation

Recommendation 10:  A ‘one-stop shop’ tool should be investigated. 

=  Commentary

By a ‘one-stop shop’ tool we meant a tool with the following characteristics:

	• GUI based, single tool that works on most OSs and allows an author to do everything they need on I-D drafting/processing in that one place. 

	• WYSIWYG interface that hides the complexity of the underlying XML, in much the same way that any modern word processor does.  (This does not have to be the only interface as some may want to work on the underlying XML).

	• Has a plugin mechanism so that any I-D processing tools can be added in for direct invocation.

	• Interacts with the Datatracker for submission and retrieval of I-Ds and associated metadata.

	• Interacts with ‘official’ IETF GitHub repositories, including for the processing of issues, pull requests and other collaboration features. (Also see recommendation 13 below)

	• Directly supports the AUTH48 process.

In order to produce such a tool, the various I-D processing tools would need to be refactored to work as plugins, going back to the concept under recommendation 6 with them all implemented as APIs, supporting any variety of client.

Is this something the TAS Team would like to start the ball rolling on recognising that there would be lots of community discussion required?

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 9 Apr 2021 14:40:16 +1000

This seems to go against the 'small pieces loosely joined' philosophy of tool-making seen in our community (and broader technical communities, such as Unix).

It also seems to reinforce the centrality of the tools team -- i.e., if I want to get any leverage in the ecosystem (e.g., with a format validator), I have to write a plugin for the tools team, rather than writing something that merely operates on a format (see eg <https://github.com/mnot/rfc-http-validate>). I don't think that's something we should be doing.

Finally, writing a multi-OS GUI tool to 'do everything' is NOT a small undertaking. I'd like to see a trend towards smaller, more controlled tools, not bigger ones.

Cheers,

> On 9 Apr 2021, at 11:13 am, Jay Daley <[email-masked]> wrote:
> 
> =  Recommendation
> 
> Tools-arch mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-arch

--
Mark Nottingham   https://www.mnot.net/

---

From: Jay Daley <[email-masked]>
Date: Fri, 9 Apr 2021 17:25:03 +1200

I understand the concerns but this came through from multiple respondents who consider our DIY, multi-tool approach to be a big barrier to participation so I would really like us to think through the details before coming to a view. 

For example, I can see how we might achieve this using Atom as a base editor as that has XML, XSLT, schema validation and version control already handled by existing plugins and us writing new plugins for 
- data tracker submission/retrieval
- YANG validators
- conversion to TXT, PDF etc
- boilerplate insertion/update
- and so on

If those plugins are actually just lightweight clients of central APIs that deliver the heavy lifting then it becomes even easier. 

Jay

-- 
Jay Daley
IETF Executive Director

> On 9/04/2021, at 4:40 PM, Mark Nottingham <[email-masked]> wrote:
>

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 9 Apr 2021 15:58:14 +1000

I think my concern here is that the way this is phrased (e.g., with 'plugins'), it appears that we're going to 'pick a winner' -- always a bad idea when it comes to editors and developers! -- and centre the work around that.

I'd like to see the emphasis on providing discrete, atomic functions in the most generic way possible, which can then accommodate adaptation to different ecosystems (e.g., various editors, web UIs, CLI, etc.). The Tools team might even provide some of those adaptations, and might package it up in a way that's easy for newcomers to consume, and might even promote that packaging so that they can find it more easily. But it should also be possible for others to provide different adaptations, and we should facilitate that (e.g., by helping them promote them to the community).

Does that make sense?

> On 9 Apr 2021, at 3:25 pm, Jay Daley <[email-masked]> wrote:
>

---

From: Jay Daley <[email-masked]>
Date: Fri, 9 Apr 2021 18:50:28 +1200

> On 9/04/2021, at 5:58 PM, Mark Nottingham <[email-masked]> wrote:
> 

Yes and I think we want the same goals but I don’t think we’re talking about mutually exclusive solutions. 

Imagine we were to give people everything they wanted:
- ability to use XML or Markdown or ?? end to end
- a single one-stop-shop tool and all the tools as separate command line tools, as separate web interfaces, as separate plugins to their favourite editor, as separate automatable services 
- ability to integrate with GitHub, GitLab, Bitbucket, etc

Then could we do it and how could we do it?  I think this is exactly the problem that APIs solve - we build and maintain a central set of functionality that is exposed by API, we build plugins to a chosen tool to give the one-stop-shop, we build separate web interfaces on top of those same APIs and we build separate CLI tools that call those APIs. If others want to build a plug-in for their favourite editor then all they need do is build calls to the API, nothing more. 

Jay

-- 
Jay Daley
IETF Executive Director

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 19 Apr 2021 11:36:21 +1000

On Fri, Apr 9, 2021, at 16:50, Jay Daley wrote:
> - a single one-stop-shop tool and all the tools as separate command 
> line tools, as separate web interfaces, as separate plugins to their 
> favourite editor, as separate automatable services 

My experience with these integrations is that they rot too fast to be useful long-term.  At various times in my career I have used numerous integrated chains, but they all ultimately break down pretty quickly.  For an enterprise, there is value in standardizing on a single integrated solution, but that requires deliberate, sustained effort.  With <40 developers at one shop, the Eclipse integration we had was a huge productivity boost.  But that was largely because the tool already provided such immense generic value for Java development that the incremental effort really paid off.

We have two countervailing forces at work here: 

1. The community that can't even decide what Markdown variant to use.  Most even seem to prefer XML.  I can't pretend to understand why.  They certainly can't be expected to agree on an editor.
2. The value an integrated tool might provide is at best minimal.  That is, the functions we might rely on are either generic to all text editors, or entirely bespoke (and therefore unlikely to be well-integrated).

So it's all about cost-benefit.  My sense is that integration work is unlikely to produce significant productivity gains.

I tend to think that the sorts of tool that Mark has produced here in https://pypi.org/project/sf-rfc-validate/ is exactly the sort of thing we need more of.  That is, something that takes a well-defined format and produces a succinct report.  Linting tools like that are an area we could improve (with yang validation being another example; idnits is almost a counter-example as it aims to be all-encompassing and integrated, to its own detriment).  Having more linters wouldn't be so bad.

Speaking of which, we need a way to filter documents for sourcecode; we shouldn't need to build that functionality multiple times.  There's a nice tool/library idea.

There are also other unexplored areas, if we want to speculate.  I've recently realized that a ctags-like tool might be worth building as well, which would lead to a lightweight, targeted integration for editors.

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 19 Apr 2021 12:15:16 +1000

> On 19 Apr 2021, at 11:36 am, Martin Thomson <[email-masked]> wrote:
> 

Just to pop up a level -- we also need to a reasonable, fair, and accountable way to decide when/if such tools are funded. E.g., AIUI we've invested non-trivial amounts of money into the YANG toolset, but that only serves a very specialised part of the community.

Cheers,