diff options
| -rw-r--r-- | CONTRIBUTING.md | 74 | ||||
| -rw-r--r-- | README.md | 161 | ||||
| -rw-r--r-- | src/eclipse/README.md | 23 |
3 files changed, 187 insertions, 71 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c05b4fd6b..e9505c26df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,66 +1,52 @@ -# Scala Project & Developer Guidelines +# Welcome! Thank you for contributing to Scala! +We follow the standard GitHub [fork & pull](https://help.github.com/articles/using-pull-requests/#fork--pull) approach to pull requests. Just fork the official repo, develop in a branch, and submit a PR! -These guidelines are meant to be a living document that should be changed and adapted as needed. We encourage changes that make it easier to achieve our goals in an efficient way. +You're always welcome to submit your PR straight away and start the discussion (without reading the rest of this wonderful doc, or the `READMEnot^H^H^H.md`). The goal of these notes is to make your experience contributing to Scala as smooth and pleasant as possible. We're happy to guide you through the process once you've submitted your PR. -## General Workflow +## The Scala Community +Last year, you -- the Scala community -- matched the core team at EPFL in number of commits contributed to Scala 2.11, doubling the percentage of commits from outside EPFL/Typesafe since 2.10. Excellent work! (The split is roughly 25/25/50 for you/epfl/typesafe. By the way, the team at Typesafe is: @adriaanm, @gkossakowski, @lrytz and @retronym.) -This is the process for committing code to the Scala project. There are of course exceptions to these rules, for example minor changes to comments and documentation, fixing a broken build etc. +We are super happy about this, and are eager to make your experience contributing to Scala productive and satisfying, so that we can keep up this growth. We can't do this alone (nor do we want to)! -1. Make sure you have signed the [Scala CLA](http://typesafe.com/contribute/cla/scala), if not, sign it. -2. Before starting to work on a feature or a fix, it's good practice to ensure that: - 1. There is a ticket for your work in the project's issue tracker. If not, create it first (perhaps given a thumbs up from the scala-internals mailing list first). - 2. The ticket has been discussed and prioritized by the team. -3. You should always perform your work in its own Git branch. The branch should be given a descriptive name that explains its intent. Some teams also like adding the ticket number and/or the [GitHub](http://github.com) user ID to the branch name, these details is up to each of the individual teams. (See below for more details on branch naming.) -4. When the feature or fix is completed you should open a [Pull Request](https://help.github.com/articles/using-pull-requests) on GitHub. -5. The Pull Request should be reviewed by other maintainers (as many as feasible/practical). Note that a reviewer can also be an outside contributor-- members of Typesafe and independent contributors are encouraged to participate in the review process. It is not a closed process. Please try to avoid conflict of interest -- the spirit of the review process is to evenly distribute the understanding of our code base across its maintainers as well as to load balance quality assurance. Assigning a review to a "sure win" reviewer is not a good long-term solution. -6. After the review, you should resolve issues brought up by the reviewers as needed (pushing a new commit to address reviewers' comments), iterating until the reviewers give their thumbs up, the "LGTM" (acronym for "Looks Good To Me"). -7. Once the code has passed review the Pull Request can be merged into the distribution. +This is why we're collecting these notes on how to contribute, and we hope you'll share your experience to improve the process for the next contributor! (Feel free to send a PR for this note, send your thoughts to scala-internals, or tweet about it to @adriaanm.) -## Pull Request Requirements +## What kind of PR are you submitting? -First, please have a look at and follow the [Pull Request Policy](https://github.com/scala/scala/wiki/Pull-Request-Policy) for guidelines on submitting a pull request to the Scala project. +Regardless of the nature of your Pull Request, we have to ask you to sign the [Scala CLA](http://typesafe.com/contribute/cla/scala), to protect the OSS nature of the code base. -In order for a Pull Request to be considered, it has to meet these requirements: +### Documentation +Whether you finally decided you couldn't stand that annoying typo anymore, you fixed the outdated code sample in some comment, or you wrote a nice, comprehensive, overview for an under-documented package, some docs for a class or the specifics about a method, your documentation improvement is very much appreciated, and we will do our best to fasttrack it. -1. Live up to the current code standard: - - Not violate [DRY](http://programmer.97things.oreilly.com/wiki/index.php/Don%27t_Repeat_Yourself). - - [Boy Scout Rule](http://programmer.97things.oreilly.com/wiki/index.php/The_Boy_Scout_Rule) should be applied. -2. Tests are of paramount importance. -3. The code must be well documented in the project's standard documentation format (see the ‘Documentation’ section below). +You can make these changes directly in your browser in GitHub, or follow the same process as for code. Up to you! -If *all* of these requirements are not met then the code should **not** be merged into the distribution, and need not even be reviewed. +For bigger documentation changes, you may want to poll the (scala-internals) mailing list first, to quickly gauge whether others support the direction you're taking, so there won't be any surprises when it comes to reviewing your PR. -## Documentation +### Code +For bigger changes, we do recommend announcing your intentions on scala-internals first, to avoid duplicated effort, or spending a lot of time reworking something we are not able to change at this time in the release cycle, for example. -All contributed code should come accompanied with documentation. Pull requests containing undocumented code will not be accepted. Both user-facing Scaladoc comments, as well as committer-facing internal documentation (i.e. important design decisions that other maintainers should know about should be placed inline with line comments `//`) should be accompanying all contributed code where possible. +The kind of code we can accept depends on the life cycle for the release you're targeting. The current maintenance release (2.11.x) cannot break source/binary compatibility, which means public APIs cannot change. It also means we are reluctant to change, e.g., type inference or implicit search, as this can have unforeseen consequences for source compatibility. +#### Bug Fix -## Work In Progress +Prefix your commit title with "SI-NNNN", where https://issues.scala-lang.org/browse/SI-NNNN tracks the bug you're fixing. We also recommend naming your branch after the Jira ticket number. -It is ok to work on a public feature branch in the GitHub repository. Something that can sometimes be useful for early feedback etc. If so, then it is preferable to name the branch accordingly. This can be done by either prefixing the name with ``wip-`` as in ‘Work In Progress’, or use hierarchical names like ``wip/..``, ``feature/..`` or ``topic/..``. Either way is fine as long as it is clear that it is work in progress and not ready for merge. This work can temporarily have a lower standard. However, to be merged into master it will have to go through the regular process outlined above, with Pull Request, review etc.. +Please make sure the Jira ticket's fix version corresponds to the upcoming milestone for the branch your PR targets (the CI automation will automatically assign the milestone after you open the PR). -Also, to facilitate both well-formed commits and working together, the ``wip`` and ``feature``/``topic`` identifiers also have special meaning. Any branch labelled with ``wip`` is considered “git-unstable” and may be rebased and have its history rewritten. Any branch with ``feature``/``topic`` in the name is considered “stable” enough for others to depend on when a group is working on a feature. +#### Enhancement or New Feature -## Creating Commits And Writing Commit Messages +For longer-running development, likely required for this category of code contributions, we suggest you include "topic" or "wip" in your branch name, to indicate that this is work in progress, and that others should be prepared to rebase if they branch off your branch. -Follow these guidelines when creating public commits and writing commit messages. +Any language change (including bug fixes) must be accompanied by the relevant updates to the spec, which lives in the same repository for this reason. -1. If your work spans multiple local commits (for example; if you do safe point commits while working in a feature branch or work in a branch for long time doing merges/rebases etc.) then please do not commit it all but rewrite the history by squashing the commits into one large commit which is accompanied by a detailed commit message for (as discussed in the following sections). For more info, see the article: [Git Workflow](http://sandofsky.com/blog/git-workflow.html). Additionally, every commit should be able to be used in isolation-- that is, each commit must build and pass all tests. -2. The first line should be a descriptive sentence about what the commit is doing. It should be possible to fully understand what the commit does by just reading this single line. It is **not ok** to only list the ticket number, type "minor fix" or similar. If the commit has a corresponding ticket, include a reference to the ticket number, prefixed with "SI-", at the beginning of the first line followed by the title of the ticket, assuming that it aptly and concisely summarizes the commit in a single line. If the commit is a small fix, then you are done. If not, go to 3. -3. Following the single line description (ideally no more than 70 characters long) should be a blank line followed by an enumerated list with the details of the commit. -4. Add keywords for your commit (depending on the degree of automation we reach, the list may change over time): - * ``Review by @githubuser`` - will notify the reviewer via GitHub. Everyone is encouraged to give feedback, however. (Remember that @-mentions will result in notifications also when pushing to a WIP branch, so please only include this in your commit message when you're ready for your pull request to be reviewed. Alternatively, you may request a review in the pull request's description.) - * ``Fix/Fixing/Fixes/Close/Closing/Refs #ticket`` - if you want to mark the ticket as fixed in the issue tracker (Assembla understands this). - * ``backport to _branch name_`` - if the fix needs to be cherry-picked to another branch (like 2.9.x, 2.10.x, etc) +A new language feature requires a SIP (Scala Improvement Process) proposal. For more details on submitting SIPs, see [how to submit a SIP](http://docs.scala-lang.org/sips/sip-submission.html). -Example: +#### Summary - SI-4032 Implicit conversion visibility affected by presence of "this" +1. We require regression tests for bug fixes. New features and enhancements must be supported by a respectable test suite. +2. Documentation. Yep! Also required :-) +3. Please follow these standard code standards, though in moderation (scouts quickly learn to let sleeping dogs lie): + - Not violate [DRY](http://programmer.97things.oreilly.com/wiki/index.php/Don%27t_Repeat_Yourself). + - [Boy Scout Rule](http://programmer.97things.oreilly.com/wiki/index.php/The_Boy_Scout_Rule) should be applied. - - Details 1 - - Details 2 - - Details 3 +Please also have a look at our [Pull Request Policy](https://github.com/scala/scala/wiki/Pull-Request-Policy), as well as the [Scala Hacker Guide](http://www.scala-lang.org/contribute/hacker-guide.html) by @xeno-by. -## The Scala Improvement Process -A new language feature requires a SIP (Scala Improvement Process) proposal. Note that significant additions to the standard library are also considered candidates for a SIP proposal. -For more details on submitting SIPs, see [how to submit a SIP](http://docs.scala-lang.org/sips/sip-submission.html). @@ -1,8 +1,157 @@ -This is the repository for the [Scala Programming Language](http://www.scala-lang.org). +# Welcome! +This is the official repository for the [Scala Programming Language](http://www.scala-lang.org). - - [Report an issue](https://issues.scala-lang.org); - - [Read about the development of the compiler and the standard library](http://docs.scala-lang.org/scala/); - - [Check our Jenkins status](https://scala-webapps.epfl.ch/jenkins/); +To contribute to the Scala Standard Library, Scala Compiler and Scala Language Specification, please send us a [pull request](https://help.github.com/articles/using-pull-requests/#fork--pull) from your fork of this repository! We do have to ask you to sign the [Scala CLA](http://typesafe.com/contribute/cla/scala) before we can merge any of your work into our code base, to protect its open source nature. + +For more information on building and developing the core of Scala, read on! Please also check out our [guidelines for contributing](CONTRIBUTING.md). + +We're still using Jira for issue reporting, so please [report any issues](https://issues.scala-lang.org) over there. +(We would love to start using GitHub Issues, but we're too resource-constrained to take on this migration right now.) + + +# Handy Links + - [A wealth of documentation](http://docs.scala-lang.org) + - [Scala CI](https://scala-ci.typesafe.com/) + - [Scala CI at EPFL](https://scala-webapps.epfl.ch/jenkins) - [Download the latest nightly](https://scala-webapps.epfl.ch/jenkins/job/scala-nightly-main-master/ws/dists/latest/*zip*/latest.zip); - - ... and contribute right here! Please, first read our [policy](http://docs.scala-lang.org/scala/pull-request-policy.html), our [development guidelines](CONTRIBUTING.md), -and [sign the contributor's license agreement](http://typesafe.com/contribute/cla/scala). + - Scala mailing lists: + - [Compiler and standard library development](https://groups.google.com/group/scala-internals) + - [Users of Scala](https://groups.google.com/group/scala-user) + - [Scala language discussion](https://groups.google.com/group/scala-language) + - [Scala Improvement Process](https://groups.google.com/group/scala-sips) + - [Debate](https://groups.google.com/group/scala-debate) + - [Announcements](https://groups.google.com/group/scala-announce) + +# Repository structure + +``` +scala/ ++--build.xml The main Ant build script, see also under src/build. ++--pull-binary-libs.sh Pulls binary artifacts from remote repository. ++--lib/ Pre-compiled libraries for the build. ++--src/ All sources. + +---/library Scala Standard Library. + +---/reflect Scala Reflection. + +---/compiler Scala Compiler. + +---/eclipse Eclipse project files. + +---/intellij-14 IntelliJ project templates. ++--scripts/ Scripts for the CI jobs (including building releases) ++--test/ The Scala test suite. ++--build/ [Generated] Build products output directory for ant. ++--dist/ [Generated] The destination folder for Scala distributions. +``` + +# How we roll + +## Requirements + +You'll need a Java SDK (6 or newer), Apache Ant (version 1.8.0 or above), and curl (for `./pull-binary-libs.sh`). + +## Git Hygiene + +As git history is forever, we take great pride in the quality of the commits we merge into the repository. The title of your commit will be read hundreds (of thousands? :-)) of times, so it pays off to spend just a little bit more time to polish it, making it descriptive and concise. Please take a minute to read the advice [most projects agree on](https://github.com/erlang/otp/wiki/Writing-good-commit-messages), and stick to 50-60 characters for the first line, wrapping subsequent ones at 80 (at most). + +When not sure how to formulate your commit message, imagine you're writing a bullet item for the next release notes, or describing what the commit does to the code base (use active verbs in the present tense). When your commit title is featured in the next release notes, it will be read by a lot of curious Scala users, looking for the latest improvements. Satisfy their thirst for information with as few words as possible! Also, a commit should convey clearly to your (future) fellow contributors what it does to the code base. + +Writing the commit message is a great sanity check that the commit is of the right size. If it does too many things, the description will be unwieldy and tedious to write. Chop it up (`git add -u --patch` and `git rebase` are your friends) and simplify! + +To pinpoint bugs, we often use git bisect, which is only effective when we can count on each commit building (and passing the test suite). Thus, the CI bot enforces this. Please rebase your development history into a sensible list of self-contained commits that tell the story of your bug fix or improvement. Carve them up so that the riskier bits can be reverted independently. Keep changes focussed by splitting out cleanups from refactorings from actual changes to the logic. + +This facilitates reviewing: a commit that reformats code can be judged quickly not to affect anything, so we can focus on the meat of the PR. It also helps when merging between long-running branches, reducing conflicts (or providing at least a limited scope for each one). + +Please do not @mention anyone in the commit message -- that's what the PR description and comments are for. Every time a commit is shuffled through github (in a merge in some fork, say), every @mention results in an email to that person (the core team treats them as personal email, straight to their inbox, so please don't flood us :-)). + + +## Reviewing + +Please consider nominating a reviewer for your PR in the PR's description or a comment. If unsure, not to worry -- the core team will assign one for you. + +Your reviewer is also your mentor, who will help you rework your PR so that it meets our requirements. We strive to give timely feedback, and apologize for those times when we are overwhelmed by the volume of contributions. Please feel free to ping us. You are entitled to regular progress updates and at least a quick assessment of feasibility of a bigger PR. + +To help you plan your contributions, we communicate our plans on a regular basis on scala-internals, and deadlines are tracked as due dates for [GitHub milestones](https://github.com/scala/scala/milestones). + +Once you've established some history submitting PRs, we will invite you to become a reviewer for others's code. The main goal of this whole process, in the end, is to ensure the health of the Scala project by improving the quality of the code base, the documentation, as well as this process itself. Thank you for doing your part! + +## IDE Setup +### Eclipse +Download the [Scala IDE bundle](http://scala-ide.org/download/sdk.html). It comes preconfigured for optimal performance. + + - Run `ant init` to download some necessary jars. + - Import the project (in `src/eclipse`) via `File` → `Import Existing Projects into Workspace`. Check all projects and click ok. + +For important details on building, debugging and file encodings, please see [the excellent tutorial on scala-ide.org](http://scala-ide.org/docs/tutorials/scalac-trunk/index.html) and the included README.md in src/eclipse. + +### IntelliJ 14 +Use the latest IntelliJ IDEA release and install the Scala plugin from within the IDE. + +The following steps are required to use IntelliJ IDEA on Scala trunk + - Run `ant init`. This will download some JARs to `./build/deps`, which are included in IntelliJ's classpath. + - Run src/intellij-14/setup.sh + - Open ./src/intellij-14/scala.ipr in IntelliJ + - File, Project Settings, Project, SDK. Create an SDK entry named "1.6" containing the Java 1.6 SDK. + (You may use a later SDK for local development, but the CI will verify against Java 6.) + +Compilation within IDEA is performed in "-Dlocker.skip=1" mode: the sources are built +directly using the STARR compiler (which is downloaded from maven, according to `starr.version` in `versions.properties`). + + +## Building with Ant + +NOTE: we are working on migrating the build to sbt. + +Run `ant build-opt` to build an optimized version of the compiler. +Verify your build using `ant test-opt`. + +The Scala build system is based on Apache Ant. Most required pre-compiled +libraries are part of the repository (in 'lib/'). The following however is +assumed to be installed on the build machine: + + +### Tips and tricks + +Here are some common commands. Most ant targets offer a `-opt` variant that runs under `-optimise` (CI runs the -optimize variant). + + - `./pull-binary-libs.sh` [downloads](http://typesafe.artifactoryonline.com/typesafe) all binary artifacts associated with this commit. + - `ant -p` prints out information about the commonly used ant targets. + - `ant` or `ant build`: A quick compilation (to build/quick) of your changes using the locker compiler. + +A typical debug cycle incrementally builds quick, then uses it to compile and run the file +`sandbox/test.scala` as follows: + + - `ant && build/quick/bin/scalac -d sandbox sandbox/test.scala && build/quick/bin/scala -cp sandbox Test` + +We typically alias `build/quick/bin/scalac -d sandbox` to `qsc` and `build/quick/bin/scala -cp sandbox` to `qs` in our shell. + +`ant test-opt` tests that your code is working and fit to be committed: + + - Runs the test suite and bootstrapping test on quick. + - You can run the suite only (skipping strap) with 'ant test.suite'. + +`ant docs` generates the HTML documentation for the library from the sources using the scaladoc tool in quick. +Note: on most machines this requires more heap than is allocate by default. You can adjust the parameters with ANT_OPTS. Example command line: + +``` +ANT_OPTS = "-Xms512M -Xmx2048M -Xss1M -XX:MaxPermSize=128M" ant docs +``` + + - `ant dist` builds a distribution in 'dists/latest'. + - `ant all.clean` Removes all build files and all distributions. + +### Bootstrapping concepts +NOTE: This is somewhat outdated, but the ideas still hold. + +In order to guarantee the bootstrapping of the Scala compiler, the ant build +compiles Scala in layers. Each layer is a complete compiled Scala compiler and library. +A superior layer is always compiled by the layer just below it. Here is a short +description of the four layers that the build uses, from bottom to top: + + - `starr`: the stable reference Scala release. We use an official version of Scala (specified by `starr.version` in `versions.properties`), downloaded from maven central. + - `locker`: the local reference which is compiled by starr and is the work compiler in a typical development cycle. Add `locker.skip=true` to `build.properties` to skip this step and speed up development when you're not changing code generation. In any case, after it has been built once, it is “frozen” in this state. Updating it to fit the current source code must be explicitly requested (`ant locker.unlock`). + - `quick`: the layer which is incrementally built when testing changes in the compiler or library. This is considered an actual new version when locker is up-to-date in relation to the source code. + - `strap`: a test layer used to check stability of the build. + +For each layer, the Scala library is compiled first and the compiler next. +That means that any changes in the library can immediately be used in the +compiler without an intermediate build. On the other hand, if building the +library requires changes in the compiler, a new locker must be built if +bootstrapping is still possible, or a new starr if it is not. diff --git a/src/eclipse/README.md b/src/eclipse/README.md index 5311651db5..03c7403b04 100644 --- a/src/eclipse/README.md +++ b/src/eclipse/README.md @@ -1,28 +1,9 @@ Eclipse project files ===================== -The following points describe how to get Scala to run in Eclipse: +The following points describe how to get Scala to run in Eclipse. Please also take a look at the [excellent tutorial on scala-ide.org](http://scala-ide.org/docs/tutorials/scalac-trunk/index.html). -0. To get Scala to work inside of Eclipse Kepler it is necessary to build the Scala IDE by your own -because for the moment there is no update site provided for the newest development version -of Scala. To do so enter the following commands one after the other: - - git clone https://github.com/scala-ide/scala-ide.git - cd scala-ide - ./build-all.sh clean install -Pscala-2.11.x -Peclipse-kepler -DskipTests - - After that you have an update site in `scala-ide/org.scala-ide.sdt.update-site/target/site`, which needs to be -installed in Eclipse. - -0. The second thing that needs to be done is building Scala in order to get all necessary -dependencies. To do that simply enter - - ant - - and wait until it is completed. To verify that everything has been built successfully, execute the REPL that can be found -at `scala/build/pack/bin/scala`. - -0. Import all projects inside of Eclipse by choosing `File/Import Existing Projects` +0. Import all projects into a [very recent version of Scala IDE for Eclipse](http://scala-ide.org/download/nightly.html) by choosing `File/Import Existing Projects` and navigate to `scala/src/eclipse`. Check all projects and click ok. 0. You need to define a `path variable` inside Eclipse. Define `SCALA_BASEDIR` in |