Contributing Guide

Welcome to the Computer Science Field Guide (CSFG) developer community! We have spent many years creating the CSFG, and we would love for you to get involved into making this guide as great as possible!

This page lists a set of guidelines for contributing to the project. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.

As a contributor, you agree to uphold our Code of Conduct.

Reporting Issues and Making Suggestions

This section guides you through submitting an issue or making a suggestion for the CS Field Guide project. Following these guidelines helps maintainers and the community understand your findings.

Before Submitting an Issue

  • Search the issue tracker for the issue/suggestion to see if it has already been logged. If it has, add a comment to the existing issue (even if the issue is closed) instead of opening a new one. If the issue is closed and you think it is not resolved, please reopen it.

How do I Submit a Good Issue or Suggestion?

Issues are tracked in the GitHub issue tracker (if you’ve never used GitHub issues before, read this 10 minute guide to become a master). When creating an issue, explain the problem and include additional details to help maintainers understand or reproduce the problem:

For Reporting an Issue

  • Use a clear and descriptive title for the issue to identify the problem.
  • Clearly and concisely describe the issue and provide screenshots if required.
  • Link any related existing issues.

If the issue is a code related issue, also include the following:

  • Describe the exact steps which reproduce the problem in as many details as possible. For example, how you were generating a resource. When listing steps, don’t just say what you did, explain how you did it.
  • Explain which behavior you expected to see instead and why.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
  • Include screenshots or animated GIFs if it helps explain the issue you encountered.
  • What’s the name and version of the OS you’re using?
  • What’s the name and version of the browser you’re using?
  • If the problem is related to performance, please provide specifications of your computer.

For Making a Suggestion

Explain the suggestion and include additional details to help maintainers understand the suggestion:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Clearly and concisely describe the suggestion and provide screenshots if required.
  • Explain why this suggestion would be useful to most CS Field Guide users and isn’t something that should be a implemented as a community variant of the project.
  • Link any related existing suggestions.

Note

Internal Staff Only: Assigning Issues

Our policy is to only assign a person to an issue when they are actively working on the issue. Please don’t assign yourself when you plan to do the task (for example: in the next few days), assign yourself when you begin work. This allows other team members to clearly see which tasks are available to be worked on.

Your First Code Contribution (pull request)

Unsure where to begin contributing to CS Field Guide? You can start by looking through the issue tracker.

Pull Requests

  • Include a detailed explaination of the proposed change, including screenshots and animated GIFs in your pull request whenever possible.
  • Read and apply the style guides listed below.
  • Your pull request should be on a new branch from our develop branch, that is being requested to merge back into develop. The naming conventions of branches should be descriptive of the new addition/modification. Ideally they would specify their namespace as well, for example:
    • resource/puzzle-town
    • topic/algorithms
    • issue/234
  • Link to any relevant existing issues/suggestions.
  • Add necessary documentation (if appropriate).

We aim to keep the CS Field Guide project as robust as possible, so please do your best to ensure your changes won’t break anything!

Style and Etiquette Guides

Git

  • Commits should be as descriptive as possible. Other developers (and even future you) will thank you for your forethought and verbosity for well documented commits. Generally:

    • Limit the first line to 72 characters or less
    • Reference issues and pull requests liberally
  • We use Vincent Driessen’s Git Branching Model for managing development. Please read this document to understand our branching methods, and how to perform clear branches and merges.

    Specifically for our respository:

    • We create a new branch for each task of work, no matter how small it is.
    • We create the branch off the develop branch.
    • In general, the new branch should begin with issue/ followed by the issue number.
    • When a branch is completed, a pull request is created on GitHub for review.
    • Branches are merged back into develop.

GitHub

Note

Internal Staff Only

  • Mention a user (using the @ symbol) when an issue is relevant to them.
  • Only assign yourself to an issue, when you are actively working on it.
  • The technical team may tag an author to review specific pull requests, and as a reviewer you can either approve, request changes, or just leave comments.
  • A pull request requires one review approval to be merged.
  • If multiple people are tagged as reviewers, we only need one review (unless otherwise specified). For example: For content changes, we ask that at least one member from each of the content and technical teams reviews the pull request.
  • The creator of the pull request should assign all those suitable for review.
  • The creator of the pull request is the only person who should merge the pull request. If you approve a pull request and it shows the big green button, please resist clicking it!

Project Structure

  • Directories should be all lowercase with dashes for spaces.
  • Directories and files should use full words when named, however JavaScript, CSS, and image directories can be named js/, css/, and img/ respectively.

Text (Markdown)

  • Each sentence should be started on a newline (this greatly improves readability when comparing two states of a document).

Programming

Quote from Google style guides:

Be consistent.

If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

We aim to abide by the following style guides:

Licencing

Any third-party libraries or packages used within this project should be listed within the LICENCE-THIRD-PARTY file, with a full copy of the licence available within the third-party-licences directory.

Final Comments

After reading the sections above, you should be able to answer the following questions:

  • When do I create a issue and how do I describe it?
  • When and how do I create a new Git branch to work on?
  • Internal staff only: When do I assign myself to an issue?