Improve ORT's general ways of working

[tsteenbe]

Creating this ticket as a follow up to the 2021-10-21 ORT developer meeting

Issues raised

• Breaking changes are merged, and not properly documented
• Lack of transparency outside of core contributors Bosch and HERE core: What being worked on, what's next, why certain things are implemented in the way they are.

Proposal
Create working group with 3-4 people e.g. 1 per company to draft a document with "ways of working on ORT" to work out below initial ideas discussed in the meeting:

• Align on what is the expected behavior of ORT.
• Create principles and architecture document as commit messages/code comment do not document the "bigger picture".
• Document what is planned to implemented and the things that won't (and in include the why). For the things where ORT TSC says "won't implement" we need to have a light-weight process that any ORT users can request a reconsideration of a past decision
• Set up light weight process to align on common roadmap e.g. dedicated roadmap meetings?
• Create a light weight "checklist" process for all non-trivial PRs, something like
  • Is the proposed change document in an issue?
  • Was is the change discussed in ORT developer meeting and were participants / ORT users given at least X time to give their input?
• Improve documentation regarding the "unspoken functionality" e.g. advisor, evaluator and some of the reporters lack docs.
• Create and maintain a change log so it easier for all ORT users to assess the impact / action required when they upgrade to a newer version of ORT.

[sschuberth]

My immediate gut feeling is that we should not need yet another "working group"; we already have the TSC and the community of developers in the weekly meetings. Instead of creating more organizational overhead, I'd prefer to improve our ways of working in these two existing groups. Additionally, we could have ad-hoc break-out sessions with all people from the community who are interested in driving a particular topic forward.

To the individual points:

Breaking changes are merged, and not properly documented

We do have the breaking change and release notes labels; we just need to remember making proper use of them.

Lack of transparency outside of core contributors Bosch and HERE core

That has been a long-pending point on the developer meeting's agenda, but we never really talked about it enough to conclude something. As discussed in today's developer meeting, IMO we should evaluate GitHub's new project boards to be transparent about our roadmaps.

Create principles and architecture document as commit messages/code comment do not document the "bigger picture".

For the bigger picture, how about linking the slides for all the presentations we did about ORT (and its bigger picture) from a new wiki page?

a light-weight process that any ORT users can request a reconsideration of a past decision

To me, that process is to put a discussion item onto the agenda for the developer meeting.

Improve documentation regarding the "unspoken functionality" e.g. advisor, evaluator and some of the reporters lack docs.

Docs definitely could see an improvement, but that's an ongoing process that we should track via issues / PRs like any other work; no need for a new working group here, IMO.

Create and maintain a change log

Yes, see #1901. But also here, just creating a new working group will also not give us the time to actually work on the issue.

[nikpete]

@tsteenbe I agree with Sebastian and this is also the reason why I was hesitant to name a Porsche participant for the working group last week. In my opinion the creation of a working group should be considered as a very last option. However, we did not really explore other options such as starting to improve our ways of working (at least since Porsche is part of the ORT community). On the other hand, we should definetely bring in some more structure and better prioritize initiatives, because I have the feeling that sometimes we are discussing everything at the same time. In addition, I do have a feeling that if Sebastian is on vacation or not available that our meeting results in chaos (last weeks meeting is a good example). To put it in a nutshell: Personally speaking, I am not in favor of a working group but we definetely need to introduce some improvements / structure and maybe reuse / link existing material / presentations, as suggested by Sebastian.

[tsteenbe]

Maybe the working group was a too big word - my proposal was to just get 4 folks on a 2-3 workshop calls to work out an document with improvement proposals, this is not something we can easily do in the ORT dev meeting where there are over a dozen people on the line. Some points require research (of other OSS project do this is needed) and in-depth discussion to come up with good set of proposals which is easier to do with 4 people than with > 12 in a focused call than 1 hour call with other agenda topics.

[sschuberth]

I still believe we should start lightweight and address what's IMO the most pressing need: A clearer communication about what the core contributors at Bosch and HERE plan to work on (without any promises being made).

Therefore, I propose to delete @tsteenbe's old project board, and to create a new roadmap (similar to GitHub's) using the new projects boards. Actually, to start with maybe separate roadmaps per contributing party would make sense to express and share a specific company's priorities, and we could later thing about creating a combined general roadmap from it.

For testing, I've started to create something here.

[sschuberth]

Some updates from today's backlog grooming session:

• Regarding breaking changes and missing change logs, we by now that proper SemVer-ed releases.
• Regarding transparency of core contributors and future plans, we have a public roadmap that everyone from the community is invited to participate in.
• Regarding checklists for issues / PRs, we now have issue templates and improved PR checks.

That said, there's basically nothing left in this issue that goes beyond the other documentation issues we have, so I'm closing this.