From 17acec58358dfc4b4221af079a43797454e393d9 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 27 Sep 2019 08:21:58 -0600 Subject: [PATCH] reorganize to clarify branistorming + resources Includes part of #110 --- README.md | 54 ++++++++++++++++------- resources/goals.md | 32 ++++++++++++++ prior-art.md => resources/prior-art.md | 0 resources/refs.md | 12 +++++ resources/syntax-considerations.md | 28 ++++++++++++ syntax-considerations.md | 61 -------------------------- 0000-template.md => template.md | 0 7 files changed, 110 insertions(+), 77 deletions(-) create mode 100644 resources/goals.md rename prior-art.md => resources/prior-art.md (100%) create mode 100644 resources/refs.md create mode 100644 resources/syntax-considerations.md delete mode 100644 syntax-considerations.md rename 0000-template.md => template.md (100%) diff --git a/README.md b/README.md index 070052712..bb63a9335 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,43 @@ -This repository, inspired by the Rust project's RFC process, is -intended to serve as a point of discussion for the design of Racket 2. +This repository is for brainstorming and discussion about the design +of a new language that is based on Racket. -Please participate by commenting on pull requests and issues. Please -post RFCs by forking and copying `0000-template.md`, which is based on -the corresponding file in the Rust project. +# Resources -# Relevant mailing list posts +* A summary of [possible goals](resources/goals.md) -* [Racket2 and - syntax](https://groups.google.com/d/msg/racket-users/3aIPOGbGgmc/A4HHSbdxAwAJ) - from Matthew Flatt 2019/07/15 -* [Racket2 - possibilities](https://groups.google.com/d/msg/racket-users/HiC7z3A5O-k/XPR2wbSJCQAJ) - from Matthew Flatt on 2019/07/20 -* [Clarify project policy on Racket2 syntax](https://groups.google.com/d/msg/racket-users/9Eh9H1Jt28Q/JXyDBfFrAgAJ) - from Matthew Flatt on 2019/08/14 +* References to some [mailing list discussion](resources/refs.md) -# Resources +* A summary of [potential syntax guidelines](resources/syntax-considerations.md) + +* An index of syntax [prior art](resources/prior-art.md) + +# Issues as a Wish List + +GitHub **issues** for this resposistory represent a kind of wish list. +Post there for an idea about some way that you think a new language +should be different than the current Racket language. Discuss other +suggestions there. + +# Pull Requests as Draft Proposals + +GitHub **pull requests** for this repository can represent more concrete +proposals. Proposals here do not have to be exhaustive, but they +should be concrete enough to enable discussion of the pros and cons of +a specific solution. There can and should be muliple conflicting +proposals for any particular problem or direction, especially at +first. The intent is to enable brainstorming and discussion toward a +future, more-complete proposal. + +To make a draft proposal, start with "template.md" and create either a +new ".md" file or a subdirectory containing a ".md" file and other +supporting material (such as an implementation). + +# Pull Requests as Resource Updates + +GitHub **pull requests** for this repository can also be suggestions +to update resources listed above. These resources are intended to be +uncontroversial summaries, although they may point toward +controverisal or conflicting perspectives. -* An index of [prior art](prior-art.md) on syntax +For these kinds of pull requests, please include "[resource]" at the +start of the pull request title. diff --git a/resources/goals.md b/resources/goals.md new file mode 100644 index 000000000..ec75f32d6 --- /dev/null +++ b/resources/goals.md @@ -0,0 +1,32 @@ +# Motivation +[motivation]: #motivation + +This document is intended to distill the main objectives of the project as explained in various threads and provide a resource to help orient discussion. It will evolve with the discussion. + +Issues and pull requests are expected to refine and elaborate points brought up in this document. Similar to [syntax considerations](syntax-considerations.md), this should be considered a living document useful mostly for flushing out questions and reactions. + +This document, or the concepts in it, could also be used to help newcomers quickly orient themselves to some goals that may not have been apparent in the initial e-mails. For a more detailed discussion with more nuances, it's still useful to read the full threads in [prior art](prior-art.md) (among others). + +# Goals List +[goals-list]: #goals-list + +* more generics +* more consistency +* lower barriers of entry +* extend smooth, fine-grained language extensibility to a broader set of syntaxes +* make backwards-incompatible changes that reflect newer thinking (e.g., structs) + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +* What is the framework for bringing this from abstract goals to concrete steps? What about even more abstract/higher level goals? +* Should there be "sacred cows" or constraints in this document? +* What does "lower barriers" mean? What does "programmers generally" mean, given how heterogeneous that group is? HOW heterogenous is the group? (What would lower barriers *for whom*?) +* What are specific obstacles teachers have had? +* How much do we want to reach out to "non-programmer" programmers? +* Are there particular concepts we want to encourage/discourage? Lessons we want programmers to learn? + +Potentially relevant but outside the scope of this document: +* How much community support is available for tooling, etc.? +* How extensive will the interoperability between Racket2 and #lang racket be? (This is not just about syntax!) +* What will be the relationship between Racket2 and the existing #lang racket? diff --git a/prior-art.md b/resources/prior-art.md similarity index 100% rename from prior-art.md rename to resources/prior-art.md diff --git a/resources/refs.md b/resources/refs.md new file mode 100644 index 000000000..7a1435f92 --- /dev/null +++ b/resources/refs.md @@ -0,0 +1,12 @@ + +# Relevant mailing list posts + +* [Racket2 and + syntax](https://groups.google.com/d/msg/racket-users/3aIPOGbGgmc/A4HHSbdxAwAJ) + from Matthew Flatt 2019/07/15 +* [Racket2 + possibilities](https://groups.google.com/d/msg/racket-users/HiC7z3A5O-k/XPR2wbSJCQAJ) + from Matthew Flatt on 2019/07/20 +* [Clarify project policy on Racket2 syntax](https://groups.google.com/d/msg/racket-users/9Eh9H1Jt28Q/JXyDBfFrAgAJ) + from Racket project leadership on 2019/08/14 +∑ \ No newline at end of file diff --git a/resources/syntax-considerations.md b/resources/syntax-considerations.md new file mode 100644 index 000000000..47368956c --- /dev/null +++ b/resources/syntax-considerations.md @@ -0,0 +1,28 @@ +# Motivation +[motivation]: #motivation + +This document is meant to facilitate the discussion around syntactic principles by providing a record of considerations that have been brought up. The intent is to be usable both as a checklist to help in discussing specific proposals and also as a starting point for developing and refining principles in the future. + + +# Considerations List +[considerations-list]: #considerations-list + +* familiar expectations + * US high school algebra + * infix operators + * algebra-style function notation + * parens can be used for grouping +* flexible +* clean / not "noisy" +* dependent on advanced tooling/editor support +* easy to rearrange chunks of code +* distinctive +* tree resemblance +* uniformity vs texture +* macros / language extensions feel natural next to existing forms +* syntax leads to "syntax patterns" and "syntax templates" that are easy to use for macro writers +* should be easily readable and editable outside of "your favorite editor" + - users (beginners in particular) should not need to learn keybindings or advanced editor features to effectively edit code. Editing code is not easy if it requires you to use `paredit`, for instance. + - users (beginners in particular) should be able to read code in various environments, like GitHub and codeblock embeded in Markdown. Matching parens is not easy if it requires you to use rainbow parens, for instance. + +∑∑ \ No newline at end of file diff --git a/syntax-considerations.md b/syntax-considerations.md deleted file mode 100644 index 49480456f..000000000 --- a/syntax-considerations.md +++ /dev/null @@ -1,61 +0,0 @@ -# Summary -[summary]: #summary - -A collection of considerations for syntax design decisions. This is an early draft; many changes are expected, both in amount of content and organization of information. - - -# Motivation -[motivation]: #motivation - -To facilitate the discussion around syntactic principles by providing a record of considerations that have been brought up. The intent is to be usable both as a checklist to help in discussing specific proposals and also as a starting point for developing and refining principles in the future. - - -# Guide-level explanation -[guide-level-explanation]: #guide-level-explanation - -Sample ways of using this list include: -* While developing a proposal, go through this list as a source of possible perspectives not considered -* Use terminology from this list to describe the tradeoffs of your proposal -* Add to this list if there appears to be a consideration in a syntax discussion that is not described here -* Suggest a reorganization of the list to clarify or illustrate concepts -* Explore an idea on this list with a proposal or more specific set of examples - -# Considerations List -[considerations-list]: #considerations-list - -* familiar expectations - * US high school algebra - * infix operators - * algebra-style function notation - * parens can be used for grouping -* flexible -* clean / not "noisy" -* dependent on advanced tooling/editor support -* easy to rearrange chunks of code -* distinctive -* tree resemblance -* uniformity vs texture -* macros / language extensions feel natural next to existing forms -* syntax leads to "syntax patterns" and "syntax templates" that are easy to use for macro writers -* should be easily readable and editable outside of "your favorite editor" - - users (beginners in particular) should not need to learn keybindings or advanced editor features to effectively edit code. Editing code is not easy if it requires you to use `paredit`, for instance. - - users (beginners in particular) should be able to read code in various environments, like GitHub and codeblock embeded in Markdown. Matching parens is not easy if it requires you to use rainbow parens, for instance. - - -# Unresolved questions -[unresolved-questions]: #unresolved-questions - -* Do we need more guidance/exposition on the purpose and proposed usage of this document? -* As this document develops, should examples and more concrete metrics or elements be included or split into a different format? - -Potentially relevant but outside the scope of this document: -* What are the goals of the Racket2 project? Which barriers we are most interested in lowering may be part of the decision-making process. -* What will be the relationship between Racket2 and the existing #lang racket? - - -# Future possibilities -[future-possibilities]: #future-possibilities - -* Define categories of considerations -* Provide guidelines? -* Refine into a discussion framework diff --git a/0000-template.md b/template.md similarity index 100% rename from 0000-template.md rename to template.md