Merge pull request #4636 from SethTisue/contributor-stuff-from-github-wiki

salvage text from old GitHub wiki so we can shut it down

2 files changed, 94 insertions, 17 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 54334aea48..e6557d78dd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -38,18 +38,93 @@ Please make sure the JIRA ticket's fix version corresponds to the upcoming miles
 
 #### Enhancement or New Feature
 
-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.
+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.
 
 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.
 
 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).
 
-#### Summary
+## Guidelines
 
-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.
+Here is some advice on how to craft a pull request with the best possible
+chance of being accepted.
 
-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.
+### Tests
+
+Bug fixes should include regression tests -- in the same commit as the fix.
+
+If testing isn't feasible, the commit message should explain why.
+
+New features and enhancements must be supported by a respectable test suite.
+
+Some characteristics of good tests:
+
+* includes comments: what is being tested and why?
+* be minimal, deterministic, stable (unaffected by irrelevant changes), easy to understand and review
+* have minimal dependencies: a compiler bug test should not depend on, e.g., the Scala library
+
+### Documentation
+
+This is of course required for new features and enhancements.
+
+Any API additions should include Scaladoc.
+
+Consider updating the package-level doc (in the package object), if appropriate.
+
+### Coding standards
+
+Please follow these standard code standards, though in moderation (scouts quickly learn to let sleeping dogs lie):
+
+* Don't violate [DRY](http://programmer.97things.oreilly.com/wiki/index.php/Don%27t_Repeat_Yourself).
+* Follow the [Boy Scout Rule](http://programmer.97things.oreilly.com/wiki/index.php/The_Boy_Scout_Rule).
+
+Please also have a look at the [Scala Hacker Guide](http://www.scala-lang.org/contribute/hacker-guide.html) by @xeno-by.
+
+### Clean commits, clean history
+
+A pull request should consist of commits with messages that clearly state what problem the commit resolves and how.
+
+Commit logs should be stated in the active, present tense.
+
+A commit's subject should be 60 characters or less.  Overall, think of
+the first line of the commit as a description of the action performed
+by the commit on the code base, so use the active voice and the
+present tense.  That also makes the commit subjects easy to reuse in
+release notes.
+
+For a bugfix, the title must look like "SI-NNNN - don't crash when
+moon is in wrong phase".
+
+If a commit purely refactors and is not intended to change behaviour,
+say so.
+
+Backports should be tagged as "[backport]".
+
+When working on maintenance branches (e.g., 2.11.x), include "[nomerge]"
+if this commit should not be merged forward into the next release
+branch.
+
+Here is standard advice on good commit messages:
+http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+### Pass Scabot
+
+Our pull request bot, Scabot, automatically builds all the commits in a PR individually. (All, so we can `git bisect` later.)
+
+Click on the little x next to a commit sha to go to the overview of the PR validation job. To diagnose a failure, consult the console output of the job that failed.
+
+See the [scala-jenkins-infra repo](https://github.com/scala/scala-jenkins-infra) and [Scabot repo](https://github.com/) for full details on PR validation.  One tip you should know is that commenting `/rebuild` on a PR asks validation to be run again on the same commits. This is only necessary when a spurious failure occurred.
+
+### Pass code review
+
+Your PR will need to be assigned to one or more reviewers.  You can suggest reviewers yourself; if you're not sure, see the list in [README.md](README.md) or ask on scala-internals.
+
+To assign a reviewer, add a "review by @reviewer" to your PR description.
+
+NOTE: it's best not to @mention in commit messages, as github pings you every time a commit with your @name on it shuffles through the system (even in other repos, on merges,...).
+
+A reviewer gives the green light by commenting "LGTM" (looks good to me).
+
+A review feedback may be addressed by pushing new commits to the request, if these commits stand on their own.
+
+Once all these conditions are met, and we agree with the change (we are available on scala-internals to discuss this beforehand, before you put in the coding work!), we will merge your changes.
diff --git a/README.md b/README.md
index e722c88e41..2655de43de 100644
--- a/README.md
+++ b/README.md
@@ -13,18 +13,20 @@ If you need some help with your PR at any time, please feel free to @-mention an
 
                                                                                                   | username                                                       | talk to me about...                               |
 --------------------------------------------------------------------------------------------------|----------------------------------------------------------------|---------------------------------------------------|
- <img src="https://avatars.githubusercontent.com/adriaanm"     height="50px" title="Adriaan Moors"/>        | [`@adriaanm`](https://github.com/adriaanm)           | how we can help // type checker, pattern matcher, infrastructure |
- <img src="https://avatars.githubusercontent.com/SethTisue"    height="50px" title="Seth Tisue"/>           | [`@SethTisue`](https://github.com/SethTisue)         | back-end, library, improving the *welcome to Scala* experience |
- <img src="https://avatars.githubusercontent.com/retronym"     height="50px" title="Jason Zaugg"/>          | [`@retronym`](https://github.com/retronym)           | Java 8 lambdas, tricky bug detective work         |
- <img src="https://avatars.githubusercontent.com/Ichoran"      height="50px" title="Rex Kerr"/>             | [`@Ichoran`](https://github.com/Ichoran)             | the collections library, performance              |
+ <img src="https://avatars.githubusercontent.com/adriaanm"     height="50px" title="Adriaan Moors"/>        | [`@adriaanm`](https://github.com/adriaanm)           | type checker, pattern matcher, infrastructure, language spec |
+ <img src="https://avatars.githubusercontent.com/SethTisue"    height="50px" title="Seth Tisue"/>           | [`@SethTisue`](https://github.com/SethTisue)         | back-end, library, the welcome-to-Scala experience, build |
+ <img src="https://avatars.githubusercontent.com/retronym"     height="50px" title="Jason Zaugg"/>          | [`@retronym`](https://github.com/retronym)           | compiler performance, weird compiler bugs, Java 8 lambdas, REPL |
+ <img src="https://avatars.githubusercontent.com/Ichoran"      height="50px" title="Rex Kerr"/>             | [`@Ichoran`](https://github.com/Ichoran)             | collections library, performance              |
  <img src="https://avatars.githubusercontent.com/lrytz"        height="50px" title="Lukas Rytz"/>           | [`@lrytz`](https://github.com/lrytz)                 | optimizer, named & default arguments              |
- <img src="https://avatars.githubusercontent.com/VladUreche"   height="50px" title="Vlad Ureche"/>          | [`@VladUreche`](https://github.com/VladUreche)       | specialization & the scaladoc tool                |
+ <img src="https://avatars.githubusercontent.com/VladUreche"   height="50px" title="Vlad Ureche"/>          | [`@VladUreche`](https://github.com/VladUreche)       | specialization, Scaladoc tool |
  <img src="https://avatars.githubusercontent.com/densh"        height="50px" title="Denys Shabalin"/>       | [`@densh`](https://github.com/densh)                 | quasiquotes, parser, string interpolators, macros in standard library |
  <img src="https://avatars.githubusercontent.com/xeno-by"      height="50px" title="Eugene Burmako"/>       | [`@xeno-by`](https://github.com/xeno-by)             | macros and reflection |
- <img src="https://avatars.githubusercontent.com/dickwall"     height="50px" title="Dick Wall"/>            | [`@dickwall`](https://github.com/dickwall)           | process & community |
+ <img src="https://avatars.githubusercontent.com/heathermiller" height="50px" title="Heather Miller"/>      | [`@heathermiller`](https://github.com/heathermiller) | documentation |
+ <img src="https://avatars.githubusercontent.com/dickwall"     height="50px" title="Dick Wall"/>            | [`@dickwall`](https://github.com/dickwall)           | process & community, documentation |
+ <img src="https://avatars.githubusercontent.com/dragos"       height="50px" title="Iulian Dragos"/>        | [`@dragos`](https://github.com/dragos)               | specialization, back end |
+ <img src="https://avatars.githubusercontent.com/axel22"       height="50px" title="Aleksandr Prokopec"/>   | [`@axel22`](https://github.com/axel22)               | collections, concurrency, specialization |
 
-
-PS: If you have some spare time to help out around here, we would be delighted to add your name to this list! 
+P.S.: If you have some spare time to help out around here, we would be delighted to add your name to this list!
 
 # Handy Links
   - [A wealth of documentation](http://docs.scala-lang.org)
@@ -151,7 +153,7 @@ to build the compiler. You can run `sbt test` to run unit (JUnit) tests.
 Use `sbt test/it:test` to run integration (partest) tests.
 
 We would like to migrate to sbt build as quickly as possible. If you would
-like to help please contact scala-internals@ mailing list to discuss your
+like to help please use the scala-internals mailing list to discuss your
 ideas and coordinate your effort with others.
 
 ### Tips and tricks