docs: migrate CONTRIBUTING.md from Dotty repo

_overviews/contribute/index.md

@@ -40,8 +40,7 @@ scala_resources:
     icon: fa fa-bug
     link: /contribute/guide.html
   - title: Code Reviews
-    description: "Review pull requests against scala/scala, lampepfl/dotty, scala/scala-lang, scala/docs.scala-lang,
-    and others."
+    description: "Review pull requests against scala/scala, lampepfl/dotty, scala/scala-lang, scala/docs.scala-lang, and others."
     icon: fa fa-eye
     link: /contribute/codereviews.html
   - title: Core Libraries

_overviews/scala3-contribution/contribution-intro.md

@@ -11,26 +11,32 @@ This guide is intended to give new contributors the knowledge they need to
 become productive and fix issues or implement new features in Scala 3. It
 also documents the inner workings of the Scala 3 compiler, `dotc`.
 
-### A Note on Stability
+### This is a living document
 
-Keep in mind that the code for `dotc` is subject to change, with no
-guarantees of stability, so the ideas discussed in this guide may
-fall out of date, please consider contributing to this guide
-on [GitHub](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution).
+Keep in mind that the code for `dotc` is continually changing, so the ideas
+discussed in this guide may fall out of date. This is a living document, so
+please consider contributing to it on
+[GitHub](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution)
+if you notice anything out of date, or report any issues
+[here](https://github.com/scala/docs.scala-lang/issues).
 
 ### Get the Most from This Guide
 
-`dotc` is built with Scala 3, fully utilising its [new features](/scala3/new-in-scala3.html).
-It is recommended that you first have some familiarity with Scala 3
-to get the most out of this guide. You can learn more in the [language reference]({{ site.scala3ref}}).
+`dotc` is built with Scala 3, fully utilising its [new
+features](/scala3/new-in-scala3.html). It is recommended that you first have
+some familiarity with Scala 3 to get the most out of this guide. You can learn
+more in the [language reference]({{ site.scala3ref }}).
 
-Many code snippets in this guide make use of shell commands (a line beginning with `$`), and in this case
-a `bash` compatible shell is assumed. You may have to look up how to translate commands to your shell.
+Many code snippets in this guide make use of shell commands (a line beginning
+with `$`), and in this case a `bash` compatible shell is assumed. You may have
+to look up how to translate commands to your shell.
 
 ### What is a Compiler?
 
-A compiler is a program that takes as input text, representing a program in one language
-and produces as output the same program, written in another programming language.
+Let's start at the beginning and first look at the question of "what is a
+compiler?". A compiler is a program that takes as input text, representing a
+program in one language and produces as output the same program, written in
+another programming language.
 
 #### The Scala Compiler
 

_overviews/scala3-contribution/procedures-checklist.md

@@ -7,35 +7,134 @@ previous-page: procedures-testing
 next-page: arch-intro
 ---
 
-Once you solved an issue, you likely want to see your change added to the [Scala 3 repo][lampepfl/dotty].
-To do that, you need to prepare a [pull request][pull-request] with your changes. We recommend you
-follow these guidelines, [also consult the full requirements][full-list]:
+Once you solved the issue you were working on, you'll likely want to see your
+changes added to the [Scala 3 repo][lampepfl/dotty]. To do that, you need to
+prepare a [pull request][pull-request] with your changes. Assuming that the team
+is aware of what you've been working, here are some final steps that you'll want
+to keep in mind as you create your PR.
 
 ### 1. Sign the CLA
 
-Make sure you have signed the [Scala CLA][cla], if not, sign it.
+Make sure you have signed the [Scala CLA][cla]. If you have any questions about
+what this is and why it's required you can read further about it [here][cla].
 
-### 2: Is It Relevant?
+### 2. Make sure your work is on its own branch
 
-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][issues];
-2. The ticket has been discussed and there is desire for it to be implemented by the
-Scala 3 core maintainers.
+When submitting your pull request it's always best to ensure the branch name is
+unique to the changes you're working on. It's important not to submit your PR on
+your `main` branch as this blocks maintainers from making any changes to your PR
+if necessary.
 
 ### 3: Add Tests
+
 Add at least one test that replicates the problem in the issue, and that shows it is now resolved.
 
 You may of course add variations of the test code to try and eliminate edge cases.
 [Become familiar with testing in Scala 3][testing].
 
 ### 4: Add Documentation
+
 Please ensure that all code is documented to explain its use, even if only internal
-changes are made.
+changes are made. This refers to scaladocs and also any changes that might be
+necessary in the reference docs.
+
+### 5: Double check everything
+
+Here are a couple tips to keep in mind.
+
+- [DRY (Don't Repeat Yourself)][dry]
+- [Scouts Rule][scouts]
+- When adding new code try use [optional braces]. If you're rewriting old code,
+  you should also use optional braces unless it introduces more code changes
+  that necessary.
+
+### 6: Commit Messages
+
+Here are some guidelines when writing commits for Dotty.
+
+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][git-workflow]. 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 "Closes #", 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)
+
+Example:
+
+```
+fix: here is your pr title briefly mentioning the topic
+
+Here is the body of your pr with some more information
+  - Details 1
+  - Details 2
+  - Details 3
+
+Closes #2
+```
+
+### 7: Create your PR!
+
+When the feature or fix is completed you should open a [Pull
+Request](https://help.github.com/articles/using-pull-requests) on GitHub.
+
+If you're not actually finished yet and are just looking for some initial input
+on your approach, feel free to open a [Draft PR][draft]. This lets reviewers
+know that you're not finished yet. It's also a good idea to put a [wip] in front
+of your pr title to make this extra clear.
+
+Shortly after creating your pull request a maintainer should assign someone to
+review it. If this doesn't happen after a few days, feel free to ping someone on
+the [Scala Contributors Discor][discord] or tag someone on the PR. Depending on
+the type of pull request there might be multiple people that take a look at your
+changes. There might also be community input as we try to keep the review
+process as open as possible.
+
+### 8: Addressing feedback
+
+More than likely you'll get feedback from the reviewers, so you'll want to make
+sure to address everything. When in doubt, don't hesitate to ask for
+clarification or more information.
 
+Once you finally see the "LGTM" (Looks Good To Me or Let's Get This Merged)
+you're PR will be merged in!
 
 [pull-request]: https://docs.github.com/en?query=pull+requests
 [lampepfl/dotty]: https://github.com/lampepfl/dotty
 [cla]: http://typesafe.com/contribute/cla/scala
 [issues]: https://github.com/lampepfl/dotty/issues
 [full-list]: https://github.com/lampepfl/dotty/blob/master/CONTRIBUTING.md
 [testing]: {% link _overviews/scala3-contribution/procedures-testing.md %}
+[discord]: https://discord.gg/TSmY9zkHar
+[dry]: https://www.oreilly.com/library/view/97-things-every/9780596809515/ch30.html
+[scouts]: https://www.oreilly.com/library/view/97-things-every/9780596809515/ch08.html
+[optional-braces]: https://docs.scala-lang.org/scala3/reference/other-new-features/indentation.html
+[draft]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
+[git-workflow]: http://sandofsky.com/blog/git-workflow.html

_overviews/scala3-contribution/start-intro.md

@@ -9,11 +9,29 @@ next-page: procedures-intro
 
 ## First Steps
 
+### Scala CLA
+
+Sometime before submitting you're pull request you'll want to make sure you have
+signed the [Scala CLA][scala-cla]. You can read more about why we require a CLA
+and what exactly is included in it [here][scala-cla].
+
+### Making sure the team is aware
+
+Before digging into an issue or starting on a new feature it's a good idea to
+make sure an [issue][dotty-issue] or a [discussion][dotty-discussion] has been
+created outlining what you plan to work on. This is both for your and the team's
+benefit. It ensures you get the help you need, and also gives the compiler team
+a heads up that someone is working on an issue.
+
+For some small changes like documentation, this isn't always necessary, but it's
+never a bad idea to check.
+
 ### Required Tools
 
 #### Essential
 
-- [git] is essential for managing the Scala 3 code, and contributing to GitHub, where the code is hosted.
+- [git] is essential for managing the Scala 3 code, and contributing to GitHub,
+  where the code is hosted.
 - A Java Virtual Machine (JDK 8 or higher), required for running the build tool.
   - download Java from [Oracle Java 8][java8], [Oracle Java 11][java11],
    or [AdoptOpenJDK 8/11][adopt]. Refer to [JDK Compatibility][compat] for Scala/Java compatibility detail.
@@ -27,13 +45,16 @@ and with the [VS Code][vs-code] text editor you can even create interactive work
 iterative workflow.
 
 ### Clone the Code
-The code of Scala 3 is hosted on GitHub at [lampepfl/dotty].
 
-Download the code with the following commands (shown using a `bash` compatible shell):
+The code of Scala 3 is hosted on GitHub at [lampepfl/dotty]. It's best practice
+to [fork] the repo you want to work on, and then send in pull requests from your
+fork.
+
+Once you've forked the repo you'll want to clone the code with the following
+commands (shown using a `bash` compatible shell):
 
 ```bash
-$ cd workspace # or, replace `workspace` with any other directory you prefer
-$ git clone https://github.com/lampepfl/dotty.git
+$ git clone https://github.com/<your-user-name-on-github>/dotty.git
 $ cd dotty
 ```
 
@@ -58,3 +79,7 @@ hello world
 [java11]: https://www.oracle.com/java/technologies/javase-jdk11-downloads.html
 [adopt]: https://adoptopenjdk.net/
 [compat]: /overviews/jdk-compatibility/overview.html
+[scala-cla]: https://www.lightbend.com/contribute/cla/scala
+[dotty-issue]: https://github.com/lampepfl/dotty/issues
+[dotty-discussion]: https://github.com/lampepfl/dotty/discussions
+[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo