Improve readmes and add code-of-conduct and contribution pages

CODE_OF_CONDUCT.md

@@ -0,0 +1,55 @@
+Code of Conduct
+===============
+
+Like the technical community as a whole, The Ecstasy Project team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people.
+
+Diversity is one of our huge strengths, but it can also lead to communication issues and conflict. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.
+
+This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
+
+This code of conduct applies to all spaces managed by The Ecstasy Project, regardless of the medium, whether at an event, in person, by email, on the phone, via text, in forums, on the wiki, in an issue tracker, and so on. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.
+
+If you believe someone is violating the code of conduct, whether or not you are the person being affected, we ask that you report it by emailing <[email protected]>.
+
+## The Guide
+
+* Be friendly and patient.
+* Be welcoming. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
+* Be considerate. Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
+* Be respectful. Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration at times, but we cannot allow that frustration to turn into personal attacks. Members of the Ecstasy community should be respectful when dealing with other members as well as with people outside the Ecstasy community.
+* Be careful in the words that you choose. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants.
+* Harassment and other exclusionary behavior are not acceptable. This includes, but is not limited to:
+  * Violent threats or language directed against another person.
+  * Discriminatory jokes and language.
+  * Posting sexually explicit or violent material.
+  * Posting (or threatening to post) other people's personally identifying information ("doxing").
+  * Trolling, or attempts to inflame or incite others.
+  * Personal insults, especially those using racist or sexist terms.
+  * Unwelcome sexual attention.
+  * Advocating for, or encouraging, any of the above behavior.
+  * Repeated harassment of others. In general, if someone asks you to stop, then stop.
+* When we disagree, try to understand why. Disagreements, both social and technical, happen all the time and this community is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. Our strength is found in our differences. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong; listen, and empathize. When right, be gracious; when wrong, be honest.
+
+## Weapons Policy
+
+No weapons will be allowed at Ecstasy events, community spaces, or in other spaces covered by the scope of this Code of Conduct. Weapons include but are not limited to guns, explosives (including fireworks), and large knives such as those used for hunting or display, as well as any other item used for the purpose of causing injury or harm to others. Anyone seen in possession of one of these items will be asked to leave immediately, and will only be allowed to return without the weapon. Community members are further expected to comply with all state and local laws on this matter.
+
+## Consequences of Unacceptable Behavior
+
+Unacceptable behavior from any community member, including sponsors and those with decision-making authority, will not be tolerated.
+
+Anyone asked to stop unacceptable behavior is expected to comply immediately.
+
+If a community member engages in unacceptable behavior, the community organizers may take any action they deem appropriate, up to and including a temporary ban or permanent expulsion from the community without warning (and without refund in the case of a paid event).
+
+Community organizers are expected to enforce the Code of Conduct in good faith; those who choose not to enforce the Code of Conduct will face a temporary ban or permanent expulsion from the community.
+
+## Attributions
+
+Thanks to:
+
+* Django Code of Conduct
+* The Speak Up! project
+* Citizen Code of Conduct
+
+All content on this page is licensed under a Creative Commons Share-Alike license.

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+Contributing
+============
+
+Thank you for your interest in contributing to The Ecstasy Project. By participating in this project, you agree to abide by our [code of conduct](CODE_OF_CONDUCT.md).
+
+Pull requests are welcome. Before submitting your first pull request, please sign and submit either an [individual contributor agreement](./license/icla.txt) ([PDF](./license/icla.pdf)) or (if contributing as an employee of a company) an [corporate contributor agreement](./license/ccla.txt) ([PDF](./license/ccla.pdf)). Please email the signed form to <[email protected]>.
+
+## Contribution guidelines ##
+
+* _Cleanliness is next to godliness._ It is very difficult to clean things up, and very easy to make a mess, so we ask that contributions always move us in the direction of cleaning things up, and we will have to respectfully decline contributions that fail to meet that measure.
+* Fixes should include a test, and features should include a working example. We apologize in advance for the lack of having followed this rule in the early stages of the project.
+* Until an official style guide is published, please respect the styles already in use.
+* We are attempting to follow the [Git Strict Flow and GitHub Project Guidelines](https://gist.github.com/rsp/057481db4dbd999bb7077f211f53f212)
+
+## How to get started
+
+We recognize that the present stage of the project is going to be fairly challenging for most sane developers to contribute to. We apologize for that, and ask for your patience -- or better yet, please help us to improve this!
+
+From within your development directory (such as `~/Development/`) where you want to create the `./xvm/` project directory, run:
+
+> `git clone https://github.com/xtclang/xvm.git`
+
+We strongly suggest the use of the JetBrains IntelliJ IDEA IDE, even if we have no idea how they came up with that name. There is a syntax highlighting helper for IntelliJ at `./bin/Ecstasy.xml`; on macOS, there is also a shell script `./bin/xtc2IDEA.sh` that may put it in place for you. Otherwise, manually copy it into the `~/Library/Preferences/IntelliJIdea14/filetypes/` directory (replace '14' with your version) or the `~/Library/Preferences/IdeaIC2019.1/filetypes` directory (replace year and release number with your version).
+
+IDEA also has built-in Git support, and that is included in the community edition.
+
+You will need JDK 8 or later installed. You can download the JDK from: <https://aws.amazon.com/corretto/> or <https://developers.redhat.com/products/openjdk/download>. (Oracle JDK and OpenJDK are both supported, but the former has licensing issues and the latter is purposefully kept out-of-date with security updates to drive business to the former.)
+
+Creating a "xvm" project in IDEA for the `./xvm/` directory. Build the project, which compiles the Java sources. After the build completes, you should be able to run the shell script `./bin/runAll.sh` that runs various "tests" (we use the term loosely here, since we have not yet incorporated a CI model).
+
+To run an individual test in IDEA, you will find that the Ecstasy source tests are located under `./xvm/xsrc/tests`. The following instructions assume that your local repository is located at `~/Development/xvm/`, and that you are trying to compile and run `misc.x`. To compile and run the Ecstasy `misc.x` test in JetBrains IntelliJ IDEA, create a "Run/Debug Configuration" as follows:
+
+* Main class=`org.xvm.runtime.TestConnector`
+* VM options=-`Xms256m -Xmx1g -ea`
+* Program arguments=`TestMisc.xqiz.it ./tests/testTemp/misc.x`
+* Working directory=`~/Development/xvm/xsrc/`
+
+This pattern is repeated for the various test files. Note that the arguments specify the fully qualified module name first (as found in the module declaration in the file), followed by the file name.
+
+_This project is still in the proof-of-concept / prototype phase. The lack of polish in the process of "getting started" is one consequence of that phase; please feel free to help us to simplify and improve the process, the documentation, the test infrastructure, the examples, and so on._
+
+## Attributions
+
+All content on this page is licensed under a Creative Commons Attribution license.

README.md

@@ -14,6 +14,8 @@ Learn more about the language at [https://xtclang.blogspot.com/](https://xtclang
 
 Learn more about the project at [https://ecstasylang.blogspot.com/](https://ecstasylang.blogspot.com/)
 
+Please respect our [code of conduct](CODE_OF_CONDUCT.md) and each other.
+
 ## Status:
 
 - **PROOF-OF-CONCEPT ONLY!!!** (please add flashing lights, warning bells, etc.)
@@ -35,6 +37,8 @@ There are many additional "nice to haves" that we hope to complete before we fin
 
 We will only "get one chance to make a good first impression", and we are determined not to waste it. We will not ask developers to waste their time attempting to use an incomplete project. At the same time, our doors are open as widely as possible to those who desire to learn, contribute to the project, and propel us towards completion.
 
+Find out more about [how you can contribute to Ecstasy](CONTRIBUTIONS.md).
+
 ## License
 
 The license for all source code (defined as ./bin/, ./resource/, ./src, ./tests, and ./xsrc) is Apache 2.0, unless explicitly noted. We chose Apache 2.0 for its compatibility with almost every reasonable use, and its compatibility with almost every license, reasonable or otherwise.
@@ -53,12 +57,7 @@ The Ecstasy (.x) source files for the runtime library are located under xvm/xsrc
 
 Java code for the prototype is located under xvm/src/org/xvm/. This code will be deprecated and removed as it is incrementally replaced by an all-Ecstasy toolchain.
 
-A few simple Ecstasy source tests are located under xvm/xsrc/tests. The following instructions assume that your local repository is located at ~/Development, and that you are trying to compile and run "misc.x". To compile and run the Ecstasy "misc.x" test in JetBrains IntelliJ IDEA, create a "Run/Debug Configuration" as follows:
-
-* Main class=org.xvm.runtime.TestConnector
-* VM options=-Xms256m -Xmx1g -ea
-* Program arguments=TestMisc.xqiz.it ./tests/testTemp/misc.x
-* Working directory=~/Development/xvm/xsrc/
+Instructions for getting started can be found in our [Contributing to Ecstasy](CONTRIBUTIONS.md) document.
 
 ## Questions?
 

bin/Ecstasy.xml

@@ -10,12 +10,12 @@
       <option name="HAS_BRACKETS" value="true" />
       <option name="HAS_PARENS" value="true" />
     </options>
-    <keywords keywords="as;class;const;construct;enum;extends;function;implements;import;immutable;incorporates;interface;into;is;module;mixin;package;private;protected;public;service;static" ignore_case="false" />
-    <keywords2 keywords="TODO;assert;case;catch;else;false;finally;for;if;instanceof;new;null;return;super;switch;true;try;while;do;break;continue;throw" />
-    <keywords3 keywords="conditional;typedef" />
+    <keywords keywords="as;class;const;construct;enum;extends;function;implements;immutable;import;incorporates;interface;into;is;module;mixin;package;private;protected;public;service;static" ignore_case="false" />
+    <keywords2 keywords="TODO;assert;case;catch;default;else;false;finally;for;if;instanceof;new;null;return;super;switch;true;try;using;while;do;break;continue;throw" />
+    <keywords3 keywords="conditional;typedef;void;val;var" />
     <keywords4 keywords="@Auto;@Atomic;@Future;@Inject;@Lazy;@Op;@Override;@RO;@Soft;@Watch;@Weak" />
   </highlighting>
   <extensionMap>
     <mapping ext="x" />
   </extensionMap>
-</filetype>
+</filetype>

doc/bnf.x

@@ -454,7 +454,7 @@ ReturnValue
     ExpressionList
 
 SwitchStatement
-    switch "(" SwitchCondition-opt ")" "{" SwitchBlocks "}"
+    "switch" "(" SwitchCondition-opt ")" "{" SwitchBlocks "}"
 
 SwitchCondition
     SwitchConditionExpression