:toc:
:toclevels: 3

= Contributing to tech.scribd.com

toc::[]

== Getting Started

To contribute to this repository you will
link:https://guides.github.com/activities/forking/[fork this repository],
push changes to a branch in your fork, and then
link:https://help.github.com/articles/creating-a-pull-request-from-a-fork/[create as a pull request]
from that branch to the `master` branch of this repository.
Forking only needs to be done once, after which you can push changes to your fork
using the GitHub website file editor or from a local clone, as described below.


[[forking]]
=== Creating a fork

Creating a fork, aka link:https://guides.github.com/activities/forking/[forking],
makes a personal copy of another repository.
Any changes you make in your fork of the repository will not show up on the website
until they are merged (via pull request) to the `master` branch of this repository.
If you are unfamiliar with how to create a fork or how forks work, see the
link:link:https://guides.github.com/activities/forking/[GitHub tutorial on forking].

=== Using GitHub to edit files

GitHub makes it easy to add, edit, or delete individual files via their website's
link:https://help.github.com/articles/editing-files-in-your-repository/[File Editor].
This has the advantage of using the file editor is that GitHub will automatically fork (if needed),
push the changes to a branch, and open a pull request for you.
It also means you don't need to have a local clone of your fork.
The disadvantage is that you can't verify you changes locally before creating the PR,
it only works on one file at a time, and your changes are lost if you close or navigate away from the page.

=== Using a local clone

We generally recommend making changes in a
link:https://help.github.com/articles/cloning-a-repository-from-github/[local clone] of your fork.
This requires some additional tools and storage on your local machine,
and you will need a bit more technical knowledge of how to use those tools.
However, this will allow you work on multiple files as part of a single set of changes.
You'll save your changes in a local branch and then <<building, build and review>> them locally.
When they are ready you will push your changes to your your fork and submit a pull request from there.

== Building

This project uses Ruby and link:https://jekyllrb.com/[Jekyll] to statically
generate the site.


You will need a Ruby environment set up in order to build and run the site locally.

[source,bash]
---
$ bundle install
----

TO run the site locally execute:

[source, bash]
----
$ bundle exec jekyll serve
----


== Editing content

Blog posts can be found in the `_posts` directory and are created as Markdown
files. Each file corresponds to a blog post. The filenames should be the format
of `YYYY-MM-DD-url-title.md`.


In that file you need to enter some meta-data in the following format:

.2019-01-01-hello-world.md
[source,yaml]
----
---
layout: post
title: "Hello World!"
tags:
- timetravel
team: iOS
author: yourgithubname
---
----

This section is referred to as the
link:https://jekyllrb.com/docs/frontmatter/[front matter]. The `layout`
attribute tells the rendering engine to use the "post" layout.
`title` will be the displayed title of the post.

`tags` are descriptive terms for this post. You can make up new tags,
but check the `tag` directory to see tags other posters have already
used. If you use new tags, run the `generate-tags` script to populate
the `tag` directory with the appropriate files.
Tags can be used to search for all posts for a specific or area,
such as "tutorials" or "plugins".
Tags must contain only numbers and lower-case letters.
Tags must not contain spaces.
Tags should be short, generally one or two words.
Tags containing multiple words should squash all the words together,
as in "continuousdelivery" or "jenkinsworld2017".
Dashes are allowed but should be avoided unless describing a topic that contains
dashes, such as a plugin name that contains dashes.

The `team` tag should correspond to one of the keys in `_data/teams.yml`. This
will ensure that the post is categorized properly.

The `author` attribute will map your
GitHub name to author information, if this is your first time adding a blog
post, please also create an entry in `_data/authors.yml` with your author metadata.

If this is your team's first contribution to the blog, add a file for your 
team to the `_category` directory. This causes a quick link to all of your
team's posts to appear in the bottom left frame of the blog home page.

Once you have everything ready, you may
link:https://help.github.com/articles/creating-a-pull-request/[create a pull
request] containing your additions.


[[reviewing]]
== Reviewing changes

Some tips:

* Pull requests are open to public, and any GitHub user can review changes and provide feedback.
  If you are interested to review changes, please just do so (and thanks in advance!). 
  No special permissions needed
