Skip to content

Latest commit

 

History

History
157 lines (108 loc) · 11.1 KB

CONTRIBUTING.md

File metadata and controls

157 lines (108 loc) · 11.1 KB
Raw

Contributing to the Rails Girls Summer of Code website

We're always very happy about contributions to our website, so thank you for taking the time to contribute! Here you will find some guidelines about what is expected from contributors. Before getting started, please make sure you read and understand our Code of Conduct.

Table of contents

  1. Setting up and getting started
  2. Reporting a bug
  3. Suggesting a new feature
  4. Contributing to an existing issue
  5. Blog post contributions
  6. Additional info

Setting up and getting started

The Rails Girls Summer of Code website is built using Jekyll. In order to set up and run the site locally for development, you'll need to have Ruby installed on your machine, create a GitHub account, and fork our repo.
"Forking" basically just means "making a copy"; this allows you to copy our summer-of-code repo (found here) without affecting it. Follow the instructions on forking a repo and cloning your fork in the GitHub docs. When forking, you might be asked where you want to fork the repository to; select your own Github profile.
Once you're all set up, you'll have to bundle the gems using bundler and start jekyll:

gem install bundler
bundle install
jekyll serve --watch

To see the site locally, just head to http://localhost:4000 in your browser. If you are new to Jekyll, you can find more about it here. Otherwise, you're ready to go!

Reporting a bug

Before reporting a bug, please check if it has already been reported. If it hasn't and you want to file a new bug report, provide the following information:

  • Where/on which page did the error happen?
  • How can the error be reproduced?
  • What was the expected and what the actual behaviour?
  • Can you provide an error message or a screenshot that illustrates the problem?

Suggesting a new feature

We are open to suggestions and ideas to improve the website or to contribute content for our blog.
As with filing a bug report, before suggesting a new feature or giving feedback please check it has not been suggested before. And if it hasn't, feel free to share your ideas on our issue tracker!

Contributing to an existing issue

You can view all of the currently open issues on our issue tracker. Most are labeled, to give you an idea of the sort of contribution that is expected.

Finding an issue

A good starting point if you're new to open source is the list of beginner-friendly issues. These are issues that don't require much prior knowledge on our program or our website to get started. Before getting started, please check that no one else is working on the issue: this will be clear by the assigned user (if there is one) and by the issue's comments/discussion.

If it seems like no one is working on the issue, great! You've officially found an issue to work on. You can leave a comment mentioning you'd like to work on the issue. Feel free to also leave a comment with your questions if anything is unclear or if you need help: Is the issue still valid? Are there any more detailed specifications to the issue?

Creating a pull request

Once you're happy with your changes, commit them:

  • git add .
  • git commit -m "your commit message"
  • git push origin your-branch (where your-branch is the name of the branch you created at the beginning). This will push your changes to your-branch of your own fork of the summer-of-code repo on github)
  • make a pull request by navigating to your repo (http://www.github.com/your_username/summer-of-code) and your branch (your-branch), and by clicking the "Compare & Review" button, as explained here.

You can find very thorough information on Pull Requests in GitHub's documentation. The most important thing to keep in mind is that all pull requests should be made against gh-pages, which is our main branch.

Blog post contributions

Requirements

Every RGSoC team has to write two blog posts during the summer. The first blog post has to be done by August 14th; the second blog post should be submitted by September 30th.
Your team name has been added to two slots in the editorial calendar; please double-check that the date works for you and make your PR by no later than 12:00 PM UTC on that day.

Creating a new blog post

First off, go through the instructions to set up and get started. Once you have your local copy set up:

  • create a new file in the summer-of-code/blog/_posts folder (on your computer).
  • Call this file yyyy-mm-dd-your-blog-post-name.md, where yyyy-mm-dd is the publishing date for your post. Don't forget the .md extension, which stands for MarkDown.
  • Add the Jekyll header for the meta data. See any of the posts in the blog/_posts folder for an example. Include the top section including the --- lines and change the attributes where required (probably all of them except the layout attribute). The date (created_at) should be the publishing date of your post. On the twitter line, please just add your twitter handle without @ character.
  • Add all your text.
  • don't forget to save your changes ;)

IMPORTANT: If you don't add your twitter handle or remove the twitter line in front matter, the metadata will not render properly. If your team doesn't have a team twitter account, you can:

  • use one of your personal accounts or
  • use our twitter handle (RailsGirlsSoC)

Permalink

Ideally, your blog post's permalink is all lowercase letters. That's not mandatory, though, but please include the date in your blog post's permalink like so:

title: Hello World
layout: post
created_at: Sun Jul 12 2015
permalink: blog/2015-07-12-hello-world
# ...

Images

Please upload the images referenced by your blog post to the img/blog/<year> folder and name them so that they can easily be linked to your article. Uploading the images is the preferred way since externally referenced graphics may become unavailable, leaving your blog post with missing image data.

Images will be downscaled to a maximum width of approx. 600 pixels. Please do not upload images much larger than that (resize them using a very simple image manipulation tool of your choosing). As a rule of thumb: An image "heavier" than 250 kilobytes is too big. There are several tools you can use online to compress your images, for example TinyPNG or compressor.io.

Please add a line with image credits under each picture, crediting the person who took the photo or created the image by name, or linking to the source of the image if you found it on the internet (URL/website). Last but not least, be sure to respect the privacy of others when uploading photos. Adding image credits is mandatory and we will not accept any post without them.

CSS/inline styles

Where you can, please avoid adding inline styling (e.g. css that changes the color of the font or makes the images a certain size) as that slowly becomes unmanageable. Keep in mind that the website design or layout might change in the future and that the site should be mobile-friendly (i.e. absolute image sizes in pixels are discouraged).

Committing your changes and sending a pull request

All that's left is to commit your changes and make a pull request. Find all the info about it here!

Additional Info

Issue labels

We use labels to track, manage and organize issues and pull requests.

Label Name Issues Description
beginner-friendly 🔍 Less complex issues, suitable for your first steps in open source.
bug 🔍 Confirmed misbehavior of the application code.
documentation 🔍 improvements to current documentation (e.g. README, contribution files)
duplicate 🔍 Issues which have already been reported.
enhancement 🔍 "nice to have" features, but not necessary.
help-wanted 🔍 Issues which are desperately looking for contributors!
in progress 🔍 Work in progress, things which are already taken care of.
#pairwithme 🔍 Looking for someone to pair on this.
question 🔍 Feature and code related questions which are no bug reports or feature requests.
ready 🔍 Issues and pull requests which have been reviewed and are ready to be closed or merged.
styling 🔍 CSS and UI related things.
wontfix 🔍 The team has decided to not fix these things for now, e.g. because the whole feature will be replaced soon.