|
| 1 | +:toc: |
| 2 | +:toclevels: 3 |
| 3 | + |
| 4 | += Contributing to tech.scrbid.com |
| 5 | + |
| 6 | +toc::[] |
| 7 | + |
| 8 | +== Getting Started |
| 9 | + |
| 10 | +To contribute to this repository you will |
| 11 | +link:https://guides.github.com/activities/forking/[fork this repository], |
| 12 | +push changes to a branch in your fork, and then |
| 13 | +link:https://help.github.com/articles/creating-a-pull-request-from-a-fork/[create as a pull request] |
| 14 | +from that branch to the `master` branch of this repository. |
| 15 | +Forking only needs to be done once, after which you can push changes to your fork |
| 16 | +using the GitHub website file editor or from a local clone, as described below. |
| 17 | + |
| 18 | + |
| 19 | +[[forking]] |
| 20 | +=== Creating a fork |
| 21 | + |
| 22 | +Creating a fork, aka link:https://guides.github.com/activities/forking/[forking], |
| 23 | +makes a personal copy of another repository. |
| 24 | +Any changes you make in your fork of the repository will not show up on the website |
| 25 | +until they are merged (via pull request) to the `master` branch of this repository. |
| 26 | +If you are unfamiliar with how to create a fork or how forks work, see the |
| 27 | +link:link:https://guides.github.com/activities/forking/[GitHub tutorial on forking]. |
| 28 | + |
| 29 | +=== Using GitHub to edit files |
| 30 | + |
| 31 | +GitHub makes it easy to add, edit, or delete individual files via their website's |
| 32 | +link:https://help.github.com/articles/editing-files-in-your-repository/[File Editor]. |
| 33 | +This has the advantage of using the file editor is that GitHub will automatically fork (if needed), |
| 34 | +push the changes to a branch, and open a pull request for you. |
| 35 | +It also means you don't need to have a local clone of your fork. |
| 36 | +The disadvantage is that you can't verify you changes locally before creating the PR, |
| 37 | +it only works on one file at a time, and your changes are lost if you close or navigate away from the page. |
| 38 | + |
| 39 | +=== Using a local clone |
| 40 | + |
| 41 | +We generally recommend making changes in a |
| 42 | +link:https://help.github.com/articles/cloning-a-repository-from-github/[local clone] of your fork. |
| 43 | +This requires some additional tools and storage on your local machine, |
| 44 | +and you will need a bit more technical knowledge of how to use those tools. |
| 45 | +However, this will allow you work on multiple files as part of a single set of changes. |
| 46 | +You'll save your changes in a local branch and then <<building, build and review>> them locally. |
| 47 | +When they are ready you will push your changes to your your fork and submit a pull request from there. |
| 48 | + |
| 49 | +== Building |
| 50 | + |
| 51 | +This project uses Ruby and link:https://jekyllrb.com/[Jekyll] to statically |
| 52 | +generate the site. |
| 53 | + |
| 54 | + |
| 55 | +You will need a Ruby environment set up in order to build and run the site locally. |
| 56 | + |
| 57 | +[source,bash] |
| 58 | +--- |
| 59 | +$ bundle install |
| 60 | +---- |
| 61 | +
|
| 62 | +TO run the site locally execute: |
| 63 | +
|
| 64 | +[source, bash] |
| 65 | +---- |
| 66 | +$ bundle exec jekyll serve |
| 67 | +---- |
| 68 | +
|
| 69 | +
|
| 70 | +== Editing content |
| 71 | +
|
| 72 | +Blog posts can be found in the `_posts` directory and are created as Markdown |
| 73 | +files. Each file corresponds to a blog post. The filenames should be the format |
| 74 | +of `YYYY-MM-DD-url-title.md`. |
| 75 | +
|
| 76 | +
|
| 77 | +In that file you need to enter some meta-data in the following format: |
| 78 | +
|
| 79 | +.2019-01-01-hello-world.md |
| 80 | +[source,yaml] |
| 81 | +---- |
| 82 | +--- |
| 83 | +layout: post |
| 84 | +title: "Hello World!" |
| 85 | +tags: |
| 86 | +- timetravel |
| 87 | +team: iOS |
| 88 | +author: yourgithubname |
| 89 | +--- |
| 90 | +---- |
| 91 | +
|
| 92 | +This section is referred to as the |
| 93 | +link:https://jekyllrb.com/docs/frontmatter/[front matter]. The `layout` |
| 94 | +attribute tells the rendering engine to use the "post" layout. |
| 95 | +`title` will be the displayed title of the post. |
| 96 | +
|
| 97 | +`tags` are descriptive terms for this post. |
| 98 | +They can be used to search for all posts for a specific or area, |
| 99 | +such as "tutorials" or "plugins". |
| 100 | +Tags must contain only numbers and lower-case letters. |
| 101 | +Tags must not contain spaces. |
| 102 | +Tags should be short, generally one or two words. |
| 103 | +Tags containing multiple words should squash all the words together, |
| 104 | +as in "continuousdelivery" or "jenkinsworld2017". |
| 105 | +Dashes are allowed but should be avoided unless describing a topic that contains |
| 106 | +dashes, such as a plugin name that contains dashes. |
| 107 | +To see tags people have used before: |
| 108 | +
|
| 109 | +
|
| 110 | +The `team` tag should correspond to one of the keys in `_data/teams.yml`. This |
| 111 | +will ensure that the post is categorized properly. |
| 112 | +
|
| 113 | +The `author` attribute will map your |
| 114 | +GitHub name to author information, if this is your first time adding a blog |
| 115 | +post, please also create an entry in `_data/authors.yml` with your author metadata. |
| 116 | +
|
| 117 | +Once you have everything ready, you may |
| 118 | +link:https://help.github.com/articles/creating-a-pull-request/[create a pull |
| 119 | +request] containing your additions. |
| 120 | +
|
| 121 | +
|
| 122 | +[[reviewing]] |
| 123 | +== Reviewing changes |
| 124 | +
|
| 125 | +Some tips: |
| 126 | +
|
| 127 | +* Pull requests are open to public, and any GitHub user can review changes and provide feedback. |
| 128 | + If you are interested to review changes, please just do so (and thanks in advance!). |
| 129 | + No special permissions needed |
0 commit comments