Skip to content

Improve instructions to submit sips #582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 23, 2016
Merged

Improve instructions to submit sips #582

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b903b4
Improve instructions to submit sips
jvican Sep 23, 2016
957f9a0
Add @dwijnand suggestions
jvican Sep 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 15 additions & 6 deletions sips/sip-tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,30 @@ 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should refer to the README in the master branch: https://github.com/scala/scala.github.com/blob/master/README.md

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

* Create a link to your SIP in the "pending sips" section of `index.md`
* Commit your changes to your forked repository
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say "Commit your changes and push them to your forked repository".

But then do you need to also say "clone your fork" after forking?

I think it's safe to assume that anyone proposing language changes knows how to git/GitHub, so I would just keep it to the superficial facts, rather than the technical step-to-step.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer to keep this as-is. True that it's safe to assume that, but leaving it there doesn't cause any harm.

* Create a new [pull request](https://github.com/scala/scala.github.com/pull/new/gh-pages). This will notify the Scala SIP team.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think that link makes sense.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍



## 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.
* `MM` is the current month (`01` = January, `12` = December) when the proposal originated.
* `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.
Expand All @@ -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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would defer this to the details in the README rather than duplicate it here - eg. this doesn't mention using Bundler.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍