Skip to content

Latest commit

 

History

History
167 lines (98 loc) · 12.5 KB

CONTRIBUTING.md

File metadata and controls

167 lines (98 loc) · 12.5 KB
Raw

Contributing to the UCF WordPress Theme

Thank you for your interest in contributing to this project! If you are a developer for UCF and want to contribute to this theme, we'd love to hear from you.

This document outlines the best ways to submit new ideas or inform us of bugs. Please take a moment to review these guidelines before submitting new issues or pull requests in order to make the contribution process easy and effective for everyone involved.

Quick links

Using the issue tracker

The issue tracker in Github is the preferred channel for bug reports, feature requests and submitting pull requests.

Please do not use the issue tracker for personal support requests. The #help-themes Teams channel is the best place to get help with your project. See the section on getting help for more information.

Bug reports

A bug is a demonstrable problem that is caused by the code in the repository. Concise and thorough bug reports will help us fix reported problems more quickly and effectively.

Before submitting a bug report

Before you submit a new bug report, please follow these steps:

  1. Use the GitHub issue search — check if the issue has already been reported. Feel free to comment in the existing issue if it is still open and you have new information to share.

  2. Check if the issue has been fixed — if you're not running the latest version of the theme, please check your code against the repo's master branch first (master will always contain the latest, stable project code). If you are running the latest version, make sure the problem isn't already resolved in an upcoming milestone.

Submit a bug report

If you've followed the steps above and have a valid bug report to submit, you can submit it by creating a new issue in Github.

Add a descriptive, understandable title and details about the bug in the description field, following the template provided. Please try to be as detailed as possible in your report. What steps will reproduce the issue? What browser(s) and OS experience the problem? Do other browsers show the bug differently? What would you expect to be the outcome? All of the information you provide will help us quickly evaluate and fix the issue.

If you have a live example of the bug available somewhere public, please include a link in the bug report. If you're not comfortable including the URL in the Github issue (e.g. it points to a development environment), you can make a note of it in the report (e.g. "see Teams for example URL"), then share the URL in the #help-themes Teams channel.

Feature requests

We welcome new feature requests from developers across campus. Before submitting a new request, think carefully about if the proposed feature aligns with the goals of the project and with UCF's brand. We strongly encourage the discussion of new feature ideas in the UCFTeam-CAMPUS-Wordpress Team.

Please provide as much detail and context as possible to justify the inclusion of your idea in the theme. We reserve the right to deny feature requests when they don't align with the project's goals, or if said feature is already accomplishable with existing utilities/components.

You can submit a new feature request by creating a new issue in Github and filling out the provided template.

Pull requests

Please ask first before embarking on any significant pull request (e.g. implementing features, refactoring code); otherwise you risk spending a lot of time working on something that the theme's maintainers might not want to merge into the project. Pull requests should be related to existing issues that have been acknowledged by UCF Web Communications.

All pull requests should remain focused in scope and avoid containing unrelated commits.

Your pull request will be reviewed by at least one maintainer of the theme. While your code should be complete enough to be understood by the person reviewing it, we don't want to spend an extensive amount of time reviewing code--try to keep your code sample brief enough to be reviewed within one hour.

Please adhere to the coding guidelines used throughout the project (indentation, accurate comments, etc.) Code that does not adhere to these standards will not be merged into the project.

How to submit a pull request

Adhering to the following process is the best way to submit a pull request:

  1. Fork the project.

  2. Clone your fork, and configure the remotes:

    # Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/UCF-WordPress-Theme.git

# Navigate to the newly cloned directory
cd UCF-WordPress-Theme

# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/UCF/UCF-WordPress-Theme.git

  3. If you cloned a while ago, get the latest changes from upstream:

    git checkout master
git pull upstream master

  4. Create a new topic branch to contain your feature, change, or fix.

    git checkout -b <topic-branch-name>

    New branches must be branched off of the most recent existing rc-* branch (typically there will only be one open at a time), or off of master directly if no rc-* branch exists.

    Never create any new branch from the develop branch--develop exists solely for project maintainers' usage and is considered a "dirty" branch. Branches created from develop will not be merged into the project.

  5. Commit your changes in logical chunks. Please provide helpful, readable commit messages (avoid nondescriptive messages such as "bugfix" or "minor change").

    If you're making changes to scss or js files, make sure you're minifying and committing those minified file changes. scss and js file processing should be performed using gulp commands provided in the repo (see gulpfile.js)

  6. Locally merge the upstream rc-* or master branch (whichever you branched off of initially) into your topic branch:

    git merge --no-ff upstream master

  7. Push your topic branch up to your fork:

    git push origin <topic-branch-name>

  8. Open a Pull Request against the rc-* or master branch (whichever you initially branched off of.) Pull request titles and descriptions should be as descriptive and clear as possible.

Asking questions/getting help

In general, we keep conversations about distributed UCF WordPress projects on the UCFTeam-CAMPUS-Wordpress Team. This workspace is owned and managed by UCF Web Communications (Webcom). You'll need a @ucf.edu email address to join.

Whenever you post a question in this Team, please include your job title, information about the college or department you work for, as well as the site(s) you need help with to help us help you more effectively.

General questions

If you have a general question about the theme, design decisions, or any other question that isn't a help request, please post it in the #help-themes Teams channel.

Help

If you need help with using this theme on your site, check out our project documentation. If you can't find the answer to your question there, please drop us a line in the #help-themes Teams channel. You don't need to @mention anyone specific, but please note that you're using the UCF WordPress Theme when posting your question and include a link to your site if it's relevant to your question.

Code standards and style guides

Whenever you add or modify code in this repo, please follow the code style guides noted below, per language:

PHP

Adhere to the WordPress PHP Coding Standards for new or modified code.

HTML

Adhere to the mdo Code Guide.

  • Use tags and elements appropriate for an HTML5 doctype (e.g., self-closing tags).
  • Use CDNs and HTTPS when referencing third-party JS.
  • Use WAI-ARIA attributes when appropriate to promote accessibility.

CSS/Sass

Adhere to the mdo Code Guide for basic CSS formatting guidelines, except for what's noted below.

Use CSS-Tricks' Sass Style Guide for Sass-specific features (e.g. order of extends, mixin inclusions, etc in a ruleset).

  • Declaration order: declarations should be in alphabetical order.
  • Selectors: all selectors in a ruleset should be on their own line.
  • All generated color pallettes and font sizes/weights should comply with WCAG 2.0 AA contrast guidelines in their default state. Components and utilities with hover/focus/active states should try to comply with these contrast requirements whenever possible.
  • Except in rare cases, don't remove default :focus styles (via e.g. outline: none;) without providing alternative styles. See this A11Y Project post for more details.

New/modified Sass code should not throw any Sass-lint errors. We recommend using a Sass-lint integration with your IDE of choice to show linter warnings/errors as you code. This repo includes a Sass-lint config file with the desired linter rulesets for this project.

JS

Adhere to the jQuery Coding Standards and Best Practices.

  • 2 spaces (no tabs)
  • Don't use jQuery event alias convenience methods (such as $().focus()). Instead, use $().trigger(eventType, ...) or $().on(eventType, ...), depending on whether you're firing an event or listening for an event. (For example, $().trigger('focus') or $().on('focus', function (event) { /* handle focus event */ })) We do this to be compatible with custom builds of jQuery where the event aliases module has been excluded.

New/modified JavaScript code should not throw any eslint errors. We recommend using a eslint integration with your IDE of choice to show linter warnings/errors as you code. This repo includes an eslint config file with the desired linter rulesets for this project.