scribd
/
scribd.github.io
mirror of https://github.com/scribd/scribd.github.io
1
0
Fork 0
Code Issues Releases Wiki Activity
scribd.github.io/CONTRIBUTING.adoc

4.9 KiB
Raw Permalink Blame History

<html lang="en"> <head> </head>

Contributing to tech.scribd.com

Table of Contents

Getting Started

To contribute to this repository you will fork this repository, push changes to a branch in your fork, and then 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.

Creating a fork

Creating a fork, aka 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:GitHub tutorial on forking.

Using GitHub to edit files

GitHub makes it easy to add, edit, or delete individual files via their website’s 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 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 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 Jekyll to statically generate the site.

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

---
$ bundle install
----

TO run the site locally execute:

$ 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
---
layout: post
title: "Hello World!"
tags:
- timetravel
team: iOS
author: yourgithubname
---

This section is referred to as the 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 create a pull request containing your additions.

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

Last updated 2024-04-28 18:07:05 UTC
</html>