135 lines
4.9 KiB
Plaintext
135 lines
4.9 KiB
Plaintext
: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
|