Skip to content

Commit

Permalink
Updating contributor guidelines and how-to docs (devopsdays#6478)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bridgetkromhout @mattstratton
bridgetkromhout authored and mattstratton committed Mar 6, 2019
1 parent 9012b63 commit 848c203
Show file tree
Hide file tree
Showing 3 changed files with 71 additions and 55 deletions.
61 changes: 37 additions & 24 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# Contributing to devopsdays-web

This document contains the technical details on how to set up [Hugo](https://gohugo.io/) (to see your edits locally before pushing them to GitHub), and how to prepare a Pull Request for inclusion on the [devopsdays](http://www.devopsdays.org/) website.
This document contains the technical details on how to set up [Hugo](https://gohugo.io/) (to see your edits locally before pushing them to GitHub), and how to prepare a pull request to make changes to content on the [devopsdays](https://www.devopsdays.org/) website.

If you'd like to assist in contributing to the code of the website, please see [devopsdays/devopsdays-theme](https://github.com/devopsdays/devopsdays-theme).
If you'd like to assist in contributing to the code itself (as opposed to the content) of the website, please see [devopsdays/devopsdays-theme](https://github.com/devopsdays/devopsdays-theme).

## Setup

If you'd like to edit a specific devopsdays event site (and/or contribute code), here's how to get started:

### Quick Overview

1. Install [Hugo](http://gohugo.io). The version we use can be found in the `.travis.yml` file. [(Quick Install)](https://gohugo.io/getting-started/installing#binary-cross-platform)
1. Fork this repo.
1. Install [Hugo](http://gohugo.io). The current Hugo version we're using can be found in the [.circleci/config.yml](https://github.com/devopsdays/devopsdays-web/blob/master/.circleci/config.yml) file. [(Quick Install)](https://gohugo.io/getting-started/installing#binary-cross-platform)
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repo and clone a copy locally.

### View site locally

Expand All @@ -25,8 +25,7 @@ Now open `http://localhost:1313` in a browser and navigate to the content that y

## Pull requests

### Process

### Setting your fork up the first time

Make your own [fork](https://help.github.com/articles/fork-a-repo/) of the `devopsdays-web` repository.

Expand All @@ -40,59 +39,74 @@ or
git remote add upstream https://github.com/devopsdays/devopsdays-web.git
```

Before starting any new change, it is essential that you `rebase` your local repository from the upstream. Issue these commands:
You only need to create your fork once, as long as you don't delete it.


### Editing your site

1. Before starting any new change, it is essential that you `rebase` your local repository from the upstream. You may think that working from your fork is enough, but sometimes upstream changes will affect your work in ways you may not anticipate, so you'll want to stay current. Issue these commands:


- `git checkout master`
- `git pull upstream master --rebase`


This confirms you are on the master branch locally, and then applies the changes from the upstream to your copy.
This confirms you are on the master branch locally, and then applies the changes from the upstream to your copy.


Create a new local [branch](https://help.github.com/articles/about-branches/) for your changes. This helps to keep things tidy!
2. Create a new local [branch](https://help.github.com/articles/about-branches/) for your changes. This helps to keep things tidy!

```
$ git checkout -b fix_that_thing
```
(Replace `fix_that_thing` with a quick description of your *actual* change.)


Make your changes, test them locally (see above), then push that branch up to `origin` on your fork.
3. Make your changes, test them locally (see above), then push that branch up to `origin` on your fork.

```
$ git push origin fix_that_thing
```

6. Submit a [Pull Request](https://help.github.com/articles/using-pull-requests/) for the branch you just pushed. Please title the pull request according to the event affected, i.e., `[CHI-2017] Add Bluth Company as a sponsor`
7. Take a break - you've earned it!
8. When a commit is merged to `master` on GitHub (ideally via a PR reviewed by at least one other person), `Netlify` (a build tool) will automatically build the site and publish it to [http://www.devopsdays.org](http://www.devopsdays.org).
4. Submit a [Pull Request](https://help.github.com/articles/using-pull-requests/) for the branch you just pushed. Please title the pull request according to the event affected, i.e., `[CHI-2017] Add Bluth Company as a sponsor`
5. Optionally, open your [pull request](https://github.com/devopsdays/devopsdays-web/pulls) in a browser and look at the preview that `Netlify` (a build tool) built.
6. You can mention on devopsdays Slack's #website if you'd like a PR merged quickly. (Availability of maintainers varies.)
7. When a commit is merged to `master` on GitHub, Netlify will automatically build the site and publish it to [https://www.devopsdays.org](https://www.devopsdays.org).

### Guidelines

1. Code changes that affect the overall site will be merged only in the [devopsdays-theme](https://github.com/devopsdays/devopsdays-theme) repo. Theme changes should be made there, and when released, will be used in this repo.
1. We use [github issues](https://github.com/devopsdays/devopsdays-theme/issues) to track work, so feel free to create new issues if you like (or read/comment on existing ones).
1. Code changes that affect the overall site will be merged only in the [devopsdays-theme](https://github.com/devopsdays/devopsdays-theme) repo. Theme changes should be made there, and when released, will be used in the `devopsdays-web` repo.
1. We use [github issues](https://github.com/devopsdays/devopsdays-theme/issues) to track work, so feel free to create new issues if you like (or read/comment/work on existing ones).
1. If you are proposing a change that affects the overall site, and is not tied to an existing issue, please open a [new issue](https://github.com/devopsdays/devopsdays-theme/issues) so that it can be discussed by the team, prior to submitting a pull request.
1. If you're using CRLF line terminators (like on Windows), the site won't build correctly if the first `+++` line of frontmatter in speaker and program files ends in a space like `+++ `. The [workaround](https://github.com/devopsdays/devopsdays-theme/issues/652) is to remove the trailing space.

### How Changes are Merged
- A maintainer will merge the PR if it is mergable, as soon as the checks pass.
- If you do not want your PR merged immediately, in most cases you should not open the PR.
- Our [workflow guide](https://github.com/devopsdays/devopsdays-web/blob/master/utilities/docs/workflow/README.md) provides solutions to most `WIP` use cases without opening a PR.
- Questions about specific cases not covered in the guide can be be asked in the #website channel on devopsdays slack.
- Questions about specific cases not covered in the guide can be asked in the #website channel on devopsdays Slack.

### Acceptable changes

- In general, only make changes to event content files. "Event content" means anything inside the `/content/...`, `/data/...`, or `/static/...` directories.
- Changes to event-specific content should be submitted in a separate PR from changes to more general content for the whole site.

### Minimal large files

### Only make changes to event content files
"Content" means anything inside the `/content/...`, `/data/...`, or `/static/...` directories.
Generally speaking, you should avoid storing any files other than logos or small images inside the repo itself (out of consideration for your fellow devopsdays organizers who have to pull down this repo). Please follow these guidelines:

Changes to event-specific content should be submitted in a separate PR from changes to more general content for the whole site.
* Do not upload presentations or other artifacts from your event into this repo. Either link to the presentation on Speakerdeck/Slideshare from the presenter, or even better, create a Speakerdeck account for your event and put the presos there.
* Small web images are fine (logos, etc). If you have high-resolution versions of your logo to share with others, please do not host them on the devopsdays-web repo.
* It is acceptable to add in a single PDF for your sponsor prospectus if you desire (in `static/events/YYYY-city`), but please keep this file under 3 MB. It is better to host it on Google Drive or something similar, and then link to it from your site.
* OPTIONAL - you can host your PDFs for prospectus, etc, in the repo at [devopsdays/devopsdays-assets](https://github.com/devopsdays/devopsdays-assets) and then link to them from there. Files in that repo are presented under their relative URL at https://assets.devopsdays.org. For example, the file located at `static/events/2016/chicago/devopsdays-chicago-2016-prospectus.pdf` in the `devopsdays/devopsdays-assets` repo will be presented at `https://assets.devopsdays.org/events/2016/chicago/devopsdays-chicago-2016-prospectus.pdf`


## Maintainer Guidelines

If you have permissions to merge PRs on this repo, here are a few guidelines to consider:

1. Is the requestor authorized to make changes for that event? They need to appear on the contact list for the year and city they're editing.
1. Do not allow any PRs that change files outside of the above-mentioned "content" directories. Especially watch out for `.gitignore`, `config.toml`, `config-windows.toml`, and anything in the `themes` directory. Our bot will notify maintainers for any changes to non-content files and assign the PR's to the maintainers, so that should help.
1. Do not allow any PRs that change files outside of the above-mentioned "content" directories. Especially watch out for `.gitignore`, `config.toml`, `config-windows.toml`, and anything in the `themes` directory. Our bot will notify maintainers for any changes to non-event-content files and assign the PRs to the maintainers, so that should help.
1. Check to see if the tests pass, but use your judgement on merging something that fails (see "PR Tests" below for guidance)
1. If you are unsure about merging a PR, please use the "request a review" button on the PR to request one from other maintainers.
1. If you're reviewing all the details of a PR before merging or are communicating with the *Submitter*, add yourself to *Assignees* so that others know someone is waiting on a response or reviewing all the details of the PR thoroughly. Be sure to also add a comment into the PR that you are reviewing it, and if you need a change from the *Submitter* prior to merge, be sure to label the PR as `do-not-merge`.
Expand All @@ -101,10 +115,9 @@ If you have permissions to merge PRs on this repo, here are a few guidelines to

The following tests run when a PR is submitted:

1. [Travis](https://travis-ci.org/devopsdays/devopsdays-web/) - this is a basic test that confirms that the site can be built with Hugo on linux, and it runs an `html-min` gulp task which will identify if there is any invalid HTML in the site. This protects the final build, so if the Travis tests fail, please take a look as to why they failed.
1. [Appveyor](https://ci.appveyor.com/project/DevOpsDays/devopsdays-web) - this again is a small test that builds Hugo on Windows, to ensure that no Windows-incompatible files have been included. If Appveyor tests fail, merge at your own discretion, based upon the failure reason.
1. [Gitmagic](https://gitmagic.io/) - This is a bot that makes sure our pull requests are fashioned cleanly. See [contributing.json](https://github.com/devopsdays/devopsdays-web/blob/master/contributing.json) for a list of rules that we enforce.
1. [Netlify](https://app.netlify.com/sites/devopsdays-web) - This is a very useful test. It builds the site, and hosts an ephemeral preview version of it (viewable by clicking on the "details" link next to the test once it has turned green). It's pretty important to view this "deploy preview" if the PR has changed anything significant (adding a sponsor, etc, probably not...but changing content in a large way? Yes.)
1. [CircleCI](https://circleci.com/gh/devopsdays/devopsdays-web) - this test confirms that the site can be built with Hugo on linux, and it runs an `html-min` gulp task which will identify if there is any invalid HTML in the site. This protects the final build, so if the CircleCI build or test jobs fail, please take a look as to why they failed.
1. [Appveyor](https://ci.appveyor.com/project/DevOpsDays/devopsdays-web) - this test builds Hugo on Windows, to ensure that no Windows-incompatible files have been included. If Appveyor tests fail, merge at your own discretion, based upon the failure reason.
1. [Netlify](https://app.netlify.com/sites/devopsdays-web) - this test builds the site, and hosts an ephemeral preview version of it (viewable by clicking on the "details" link next to the test once it has turned green). It's a good idea to view this "deploy preview" if the PR has changed anything significant (adding a sponsor, etc, probably not...but changing content in a large way? Yes.)

## Credits

Expand Down
31 changes: 12 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,30 @@
[![Build Status](https://travis-ci.org/devopsdays/devopsdays-web.svg?branch=master)](https://travis-ci.org/devopsdays/devopsdays-web) [![Build status](https://ci.appveyor.com/api/projects/status/3lobrrssphdb20xd?svg=true)](https://ci.appveyor.com/project/DevOpsDays/devopsdays-web)
[![Build Status](https://circleci.com/gh/devopsdays/devopsdays-web.svg?branch=master)](https://circleci.com/gh/devopsdays/devopsdays-web) [![Build status](https://ci.appveyor.com/api/projects/status/3lobrrssphdb20xd?svg=true)](https://ci.appveyor.com/project/DevOpsDays/devopsdays-web)
[![license](https://img.shields.io/github/license/devopsdays/devopsdays-theme.svg)](https://github.com/devopsdays/devopsdays-web/blob/master/LICENSE) [![Greenkeeper badge](https://badges.greenkeeper.io/devopsdays/devopsdays-web.svg)](https://greenkeeper.io/)


# devopsdays-web

This is the repo for managing [devopsdays.org](http://www.devopsdays.org).

## Managing event content
## Managing your event content

Reference documentation for the currently available theme is available in [themes/devopsdays-theme/REFERENCE.md](https://github.com/devopsdays/devopsdays-web/blob/master/themes/devopsdays-theme/REFERENCE.md).
If you are on a local devopsdays team and you'd like to edit [devopsdays.org](http://www.devopsdays.org) for your events, you're in the right place.

Instructions and utilities are available for [managing sponsors, events, speakers, and more](utilities/README.md).
Guidelines for contributing event-specific content to this repository are outlined in [CONTRIBUTING.md](CONTRIBUTING.md). If you intend to contribute (and we hope you do!), please take a moment to review that document so you can get set up correctly.

## Reporting issues
When you're ready to add content, instructions and utilities are available for [managing sponsors, events, speakers, and more](utilities/README.md).

If you discover an issue with the theme, please open an issue in the [devopsdays-theme repo](https://github.com/devopsdays/devopsdays-theme/issues/new).
## Site-wide Hugo theme

## Binary files
You may find that you want to improve the site in some way that's not specific to your event. We use a custom Hugo theme, and reference documentation is available in [themes/devopsdays-theme/REFERENCE.md](https://github.com/devopsdays/devopsdays-web/blob/master/themes/devopsdays-theme/REFERENCE.md).

Generally speaking, you should avoid storing any files other than logos or small images inside the repo itself (out of consideration for your fellow devopsdays organizers who have to pull down this repo). Please follow these guidelines:
The technical details for contributing to the site-wide theme's development are covered in [devopsdays-theme's CONTRIBUTING.md](https://github.com/devopsdays/devopsdays-theme/blob/master/CONTRIBUTING.md).

* Do not upload presentations, artifacts from your event, etc. Either link to the preso on Speakerdeck/Slideshare from the presenter, or even better, create a Speakerdeck account for your event and put the presos there.
* Small, web images are fine (logos, etc). If you have high-resolution versions of your logo to share with others, please do not host them on the devopsdays-web repo.
* It is acceptable to add in a single PDF for your sponsor prospectus if you desire (in `static/events/YYYY-city`), but please keep this file under 3 MB. It is better to host it on Google Drive or something similar, and then link to it from your site.
* OPTIONAL - you can host your PDF's for prospectus, etc, in the repo at [devopsdays/devopsdays-assets](https://github.com/devopsdays/devopsdays-assets) and then link to them from there. Files in that repo are presented under their relative URL at https://assets.devopsdays.org. For example, the file located at `static/events/2016/chicago/devopsdays-chicago-2016-prospectus.pdf` in the `devopsdays/devopsdays-assets` repo will be presented at `https://assets.devopsdays.org/events/2016/chicago/devopsdays-chicago-2016-prospectus.pdf`
## Reporting issues & feature requests

## Feature Requests
If there is a feature in the theme that you would like to see, please [submit an issue](https://github.com/devopsdays/devopsdays-theme/issues/new) to this repository and prepend the title with `[ENHANCEMENT]`. If you discover an issue with the theme, [submit an issue](https://github.com/devopsdays/devopsdays-theme/issues/new) and prepend the title with `[BUG]`.
If you discover an issue with the site that isn't specific to an event's content, please open an issue in the [devopsdays-theme repo](https://github.com/devopsdays/devopsdays-theme/issues/new) and prepend the title with `[BUG]`.

If you would like to help prioritize enhancements, please upvote the original issue by [adding a reaction](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments).

## Contributing
If there is a feature that you would like to see, please [submit an issue](https://github.com/devopsdays/devopsdays-theme/issues/new) to the theme repository and prepend the title with `[ENHANCEMENT]`.

The technical details and guidelines for contributing to this repository are outlined in [CONTRIBUTING.md](CONTRIBUTING.md). If you intend to contribute (and we sure hope you do!), please take a moment to review that document.
If you would like to help prioritize enhancements, please upvote the original issue by [adding a reaction](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments).

Guidelines for contributing event-specific content to this repository are outlined in [CONTRIBUTING.md](CONTRIBUTING.md). If you intend to contribute (and we sure hope you do!), please take a moment to review that document. The technical details for contributing to the site-wide theme's development are covered in [devopsdays-theme's CONTRIBUTING.md](https://github.com/devopsdays/devopsdays-theme/blob/master/CONTRIBUTING.md).
Loading

0 comments on commit 848c203

Please sign in to comment.