CONTRIBUTING.md 5.59 KB
Newer Older
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
1 2 3 4
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

Phil Hughes's avatar
Phil Hughes committed
5
- [Contributor license agreement](#contributor-license-agreement)
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
6 7 8 9 10
- [Adding a new site example](#adding-a-new-site-example)
- [README template](#readme-template)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Phil Hughes's avatar
Phil Hughes committed
11 12 13 14 15 16 17 18
## Contributor license agreement

By submitting code as an individual you agree to the [individual contributor
license agreement][individual-agreement].

By submitting code as an entity you agree to the [corporate contributor license
agreement][corporate-agreement].

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
## Adding a new site example

The steps to add a new static site example are:

1. Create a new project named after the static generator (lowercase)
1. Add a project description which must follow the schema:

    > Example `<Name>` site using GitLab Pages: https://pages.gitlab.io/`<name>`

    where `<Name>` is the name of the static generator and the URL's `<name>`
    is taken after the project's name.

1. Add a `README.md` that has specific information, according to
   the [README template](#readme-template)

34
1. Add a new issue to https://gitlab.com/pages/pages.gitlab.io/issues, containing:
35
    - SSG name / website
36
    - Your working example: project url / website url
37
    - Yours (optional) and the SSG's Twitter handle (we'll thank you for contributing!)
38

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
39 40 41 42 43 44 45 46
## README template

The `README.md` file must contain the following information in this order:

1. Link to the build status badge
1. Introduction: what this project is about, provide links to:
    1. Official project main page
    1. <https://pages.gitlab.io>
47
    1. Pages documentation  <https://docs.gitlab.com/ce/user/project/pages/>
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
48 49 50
1. Building locally
    1. Install requirements
    1. Run local server if any
51
1. GitLab CI
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
1. Difference between user/project Pages
    - How to convert to user Pages
1. Did you fork this project?
    - Remove fork relationship

---

Use the following text as a base and build upon it:

```
![Build Status](https://gitlab.com/pages/<project>/badges/master/build.svg)

---

Example [<Project>] website using GitLab Pages.

Learn more about GitLab Pages at https://pages.gitlab.io and the official
69
documentation https://docs.gitlab.com/ce/user/project/pages/.
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
70 71 72

---

73 74 75 76 77 78 79 80 81 82 83 84
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [GitLab CI](#gitlab-ci)
- [Building locally](#building-locally)
- [GitLab User or Group Pages](#gitlab-user-or-group-pages)
- [Did you fork this project?](#did-you-fork-this-project)
- [Troubleshooting](#troubleshooting)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

85
## GitLab CI
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130

This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):

contents of .gitlab-ci.yml in codeblock

## Building locally

To work locally with this project, you'll have to follow the steps below:

1. Fork, clone or download this project
1. [Install][] <project>
1. Generate the website: `make html`
1. Preview your project: `make serve`
1. Add content

Read more at <Project>'s [documentation][].

## GitLab User or Group Pages

To use this project as your user/group website, you will need one additional
step: just rename your project to `namespace.gitlab.io`, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.

Read more about [user/group Pages][userpages] and [project Pages][projpages].

## Did you fork this project?

If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.

## Troubleshooting

1. CSS is missing! That means two things:

    Either that you have wrongly set up the CSS URL in your templates, or
    your static generator has a configuration option that needs to be explicitly
    set in order to serve static assets under a relative URL.

[ci]: https://about.gitlab.com/gitlab-ci/
[<project>]: http://link-to-project-main-page
[install]: http://link-to-install-page
[documentation]: http://link-to-main-documentation-page
131 132
[userpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#user-or-group-pages
[projpages]: https://docs.gitlab.com/ce/user/project/pages/introduction.html#project-pages
133 134 135 136

----

Forked from @<username>
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
137 138 139 140 141 142 143 144 145 146 147 148 149 150
```

---

The changes you'll have to make are:

1. Replace `<project>` and `<Project>` with the project name (**tip:** use your
   editor's search and replace function)
1. Explain the contents of `.gitlab-ci.yml`
1. Add some brief steps how to build and hack locally
1. Replace the _links_ at the bottom of the README to:
  1. `[<project>]`: The project's homepage
  1. `[install]`: The project's installation guide
  1. `[documentation]`: The project's documentation website
151
  1. `<username>`: Your username at GitLab
152 153 154
1. Use [doctoc][] to create or update the Table Of Contents: `doctoc --gitlab README.md`
   Make sure that the badge and the project info are on top. See the README
   template to take an example.
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
155 156

Leave any other information as-is.
157 158

[doctoc]: https://github.com/thlorenz/doctoc/
Phil Hughes's avatar
Phil Hughes committed
159 160
[individual-agreement]: https://docs.gitlab.com/ee/legal/individual_contributor_license_agreement.html
[corporate-agreement]: https://docs.gitlab.com/ee/legal/corporate_contributor_license_agreement.html