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

[Jean Perier via Phabricator via flang-commits]

jeanPerier created this revision.
jeanPerier added reviewers: clementval, vzakhari, awarzynski, kiranchandramohan, PeteSteinfeld, pmccormick.
jeanPerier added a project: Flang.
Herald added a subscriber: jdoerfert.
Herald added a reviewer: sscalpone.
Herald added a project: All.
jeanPerier requested review of this revision.

The goal of this document is to:

- Allow the community to contribute to flang design by defining the expectations.
- Ensure there is a minimum of consistency between future design docs.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D130166

Files:
  flang/docs/DesignGuideline.md


Index: flang/docs/DesignGuideline.md
===================================================================
--- /dev/null
+++ flang/docs/DesignGuideline.md
@@ -0,0 +1,93 @@
+<!--===- docs/DesignGuideline.md
+
+   Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+   See https://llvm.org/LICENSE.txt for license information.
+   SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+-->
+# Design Guideline
+
+```eval_rst
+.. contents::
+   :local:
+```
+## Documenting the design
+
+### Designing support for a new feature
+
+When working on a new feature in flang, some design document should
+be produced before submitting patches to the code.
+
+The preferred organization of such documents is:
+1) Problem description
+2) Proposed solution
+3) Implementation details overview
+4) Testing plan
+
+If several solutions can be considered, it is best to briefly describe the
+alternate solutions in 2) and why they were not retained.
+  
+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.
+  
+An RFC on flang https://discourse.llvm.org can first be made as one sees fit,
+but this document should still be produced to summarize, organize, and formalize
+the discussions. If a related discourse RFC was made it is a good idea to give a
+link to it in the document for future reference.
+
+### Updating the implementation solution of a feature                                                                         
+
+When doing a significant change to the implementation solution for a feature,
+the related design document should be updated so that it will justify the new
+solution.
+
+## Design tips
+
+### Design document style
+
+The document does not have to be long. It is highly encouraged to:
+- Stick to Fortran well defined terms when talking about Fortran
+  (definitions of these terms can be found in Section 3. of Fortran 2018
+  standard)
+- Be precise (e.g., pointing to the standard reference or constraint numbers).
+  References should currently be given against the Fortran 2018 standard
+  version.
+- Illustrate with a few small Fortran code snippets if applicable
+- When dealing with lowering, illustrate lowering output with a few FIR,
+  and LLVM IR code snippets
+- Illustrations do not have to be fully functional programs, it is better to
+  keep them small and focused on the feature. More detailed expectations
+  can be added in a second time or in parallel as LIT tests for example.
+
+### Thinking through the design of a Fortran feature
+
+Below is a set of suggested steps that one can take to fully apprehend a
+Fortran feature before writing a design for its implementation in flang.
+
+- Identify the relevant sections and constraints in the standard.
+- Write Fortran program using the feature and, if possible,
+  verify your expectations with existing compilers.
+- Check if the related constraints (Cxxx numbers in the standard) are enforced
+  by semantics. If not it is good idea to start by adding the related checks
+  (this does not require writing a design document).
+- Identify if the feature affects compatibility with programs compiled by other
+  Fortran compilers, or if a given solution for flang could not be changed in
+  the future without breaking compatibility with programs previously compiled
+  with flang. It is not a goal to be 100% binary compatible with other
+  compilers outside of Fortran 77, but sources of incompatibility should be
+  known and justified.
+- Identify related features, or contexts that matter for the feature (e.g,
+  does being in an internal procedure, a module, a block… changes anything
+  to what should happen?).
+- Not everything has to be inlined code, delegating part of the work to the
+  Fortran runtime may be a solution. Identify the relevant Fortran runtime
+  API if any.
+- For inlined code, consider what should happen when generating the FIR,
+  and what should happen when lowering the FIR to LLVM IR.
+- For inlined ops, look at how the existing dialects can be used,
+  if new FIR operations are required, justify their purpose.
+- Look at the related representation in Semantics (e.g., is some information
+  from the parse tree, the Symbol or evaluate::Expr required? Are there tools
+  to query this information easily?).


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D130166.446136.patch
Type: text/x-patch
Size: 4464 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/flang-commits/attachments/20220720/2be2f4bc/attachment-0001.bin>