[flang-commits] [PATCH] D130166: [flang] Adding a guideline for flang design documentation

[Kiran Chandramohan via Phabricator via flang-commits]

kiranchandramohan added inline comments.


================
Comment at: flang/docs/DesignGuideline.md:30-33
+The design document should be added to the `docs` folder as a markdown document,
+ideally using the name of the feature as the document name. Its approval on
+Phabricator is the pre-requisite to submitting patches implementing new
+features.
----------------
klausler wrote:
> kiranchandramohan wrote:
> > awarzynski wrote:
> > > jeanPerier wrote:
> > > > jeanPerier wrote:
> > > > > clementval wrote:
> > > > > > unterumarmung wrote:
> > > > > > > So, one should create a design doc first, merge it to the repository after necessary approvals and only then start to work on the feature?
> > > > > > > I'm with @awarzynski on this. I think it's more agile to first create a discourse discussion with RFC and/or design doc and then, after a mutual agreement that a feature is needed, start to work on the feature and the final design doc in the same revision.
> > > > > > I think discussion on Discourse are nice but I find it hard to summarize if you come later in the discussion or even after it. IMO The document is a better place to have the summary of what is agreed on. To get it it in tree phab is the only way. What about make a phab review for the document and advertise it in a Discourse post?
> > > > > > So, one should create a design doc first, merge it to the repository after necessary approvals and only then start to work on the feature?
> > > > > > I'm with @awarzynski on this. I think it's more agile to first create a discourse discussion with RFC and/or design doc and then, after a mutual agreement that a feature is needed, start to work on the feature and the final design doc in the same revision.
> > > > > 
> > > > > No, the guideline tells that you can first discuss on discourse if you want to, but I do not think we should mandate the discussions to happen on discourse if the person working on the feature prefers the discussions to happen as a design document review. Although, I agree with @awarzynski  point that discourse is more visible, and it makes sense to me to require people to at least advertise those in discourse.
> > > > > So, one should create a design doc first, merge it to the repository after necessary approvals and only then start to work on the feature?
> > > > > I'm with @awarzynski on this. I think it's more agile to first create a discourse discussion with RFC and/or design doc and then, after a mutual agreement that a feature is needed, start to work on the feature and the final design doc in the same revision.
> > > > 
> > > > 
> > > I suggest that:
> > > # We require all new proposal/design-docs to be //advertised// on Discourse.
> > > # People posting new proposals decide for themselves whether they prefer the discussion to continue on Discourse or Phabricator.
> > > 
> > > Basically, we let people decide what works for them best. 
> > For me, advertising in discourse should be made compulsory so that people are aware. 
> There are conference calls, mailing lists, discourse, slack, and phabricator.  Only phabricator is mandatory.
The recommended (not mandatory) guideline when making a major change is to announce it via an RFC in discourse.
https://llvm.org/docs/DeveloperPolicy.html#making-a-major-change

If people feel this is a duplication of effort then we should check whether we can make Phabricator send an automatic post to discourse when the project is flang and the subject carries the word "RFC" or "Design Document".

Also, there seems to be a decision made to move from Phabricator to Github PRs by October 2023. I don't know whether this has any impact on this process. https://discourse.llvm.org/t/code-review-process-update/63964


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D130166/new/

https://reviews.llvm.org/D130166