From 7b903b4d28dd4a1f355fec9cbd8151d7ab595e8f Mon Sep 17 00:00:00 2001 From: jvican Date: Fri, 23 Sep 2016 11:33:53 +0200 Subject: [PATCH 1/2] Improve instructions to submit sips --- sips/sip-tutorial.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/sips/sip-tutorial.md b/sips/sip-tutorial.md index 7f6b8b0458..60faa509d9 100644 --- a/sips/sip-tutorial.md +++ b/sips/sip-tutorial.md @@ -3,13 +3,23 @@ layout: sip-landing title: Writing a new SIP --- -This tutorial details of how to write a new SIP and adding it to the website. Currently two mechanisms of providing a new SIP are recommended: +This tutorial details of how to write a new SIP and adding it to the website. -* Using Markdown -* Using Google Docs. +## How do I submit? ## +The process to submit is simple: -## Writing a SIP in Markdown ## +* Fork the Scala documentation repository, [http://github.com/scala/scala.github.com](http://github.com/scala/scala.github.com). +* Create a new SIP file in the `sips/pending/_posts/`. Use the [S(L)IP template](https://github.com/scala/slip/blob/master/slip-template.md) + * Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`. + * Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP. + * Follow the instructions in the [README](https://github.com/scala/scala.github.com/blob/gh-pages/README.md) to build your SIP locally so you can ensure that it looks correct on the website. +* Create a link to your SIP in the "pending sips" section of `index.md` +* Commit your changes to your forked repository +* Create a new [pull request](https://github.com/scala/scala.github.com/pull/new/gh-pages). This will notify the Scala SIP team. + + +## SIP Post Format ## First, create a new SIP file in the `pending/_posts` directory. Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Where: * `YYYY` is the current year when the proposal originated. @@ -17,7 +27,6 @@ First, create a new SIP file in the `pending/_posts` directory. Make sure the n * `dd` is the day of the month when the proposal originated. * `{title}` is the title for the SIP. - ### Markdown formatting ### Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP. @@ -36,4 +45,4 @@ class Foo Testing changes requires installing [Jekyll](http://jekyllrb.com/docs/installation/). Since this site is hosted on github pages, make sure you have [whatever version of Jekyll that github is running](https://help.github.com/articles/using-jekyll-with-pages#troubleshooting). As of the writing of this README, that is version >= 1.0.x. -Use the `jekyll server` command to start up a local server. You can then view your changes at [http://localhost:4000/sips](http://localhost:4000/sips). +Use the `jekyll serve --watch --incremental` command to start up a local server. You can then view your changes at [http://localhost:4000/sips](http://localhost:4000/sips). From 957f9a07fdd6625e43199dd2e18662ad8aad83d0 Mon Sep 17 00:00:00 2001 From: jvican Date: Fri, 23 Sep 2016 12:46:50 +0200 Subject: [PATCH 2/2] Add @dwijnand suggestions --- sips/sip-tutorial.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/sips/sip-tutorial.md b/sips/sip-tutorial.md index 60faa509d9..9c05c6ff56 100644 --- a/sips/sip-tutorial.md +++ b/sips/sip-tutorial.md @@ -9,14 +9,14 @@ This tutorial details of how to write a new SIP and adding it to the website. The process to submit is simple: -* Fork the Scala documentation repository, [http://github.com/scala/scala.github.com](http://github.com/scala/scala.github.com). +* Fork the [Scala documentation repository](http://github.com/scala/scala.github.com) and clone it. * Create a new SIP file in the `sips/pending/_posts/`. Use the [S(L)IP template](https://github.com/scala/slip/blob/master/slip-template.md) * Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`. * Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP. - * Follow the instructions in the [README](https://github.com/scala/scala.github.com/blob/gh-pages/README.md) to build your SIP locally so you can ensure that it looks correct on the website. -* Create a link to your SIP in the "pending sips" section of `index.md` -* Commit your changes to your forked repository -* Create a new [pull request](https://github.com/scala/scala.github.com/pull/new/gh-pages). This will notify the Scala SIP team. + * Follow the instructions in the [README](https://github.com/scala/scala.github.com/blob/master/README.md) to build your SIP locally so you can ensure that it looks correct on the website. +* Create a link to your SIP in the "pending sips" section of `index.md`. +* Commit your changes and push them to your forked repository. +* Create a new pull request. This will notify the Scala SIP team. ## SIP Post Format ## @@ -45,4 +45,7 @@ class Foo Testing changes requires installing [Jekyll](http://jekyllrb.com/docs/installation/). Since this site is hosted on github pages, make sure you have [whatever version of Jekyll that github is running](https://help.github.com/articles/using-jekyll-with-pages#troubleshooting). As of the writing of this README, that is version >= 1.0.x. -Use the `jekyll serve --watch --incremental` command to start up a local server. You can then view your changes at [http://localhost:4000/sips](http://localhost:4000/sips). +After the installation, you need to start up the local server. The +[README](https://github.com/scala/scala.github.com/blob/master/README.md) gives +a concise explanation on how to do it. When the server is running, view your +changes at [http://localhost:4000/sips](http://localhost:4000/sips).