Thank you for your interest in contributing to this project! If you are a developer for UCF and want to contribute to this plugin, 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.
- Using the issue tracker
- Bug reports
- Feature requests
- Pull requests
- Asking questions/getting help
- Code standards and style guides
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-plugins Slack channel is the best place to get help with your project. See the section on getting help for more information.
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 you submit a new bug report, please follow these steps:
-
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.
-
Check if the issue has been fixed — if you're not running the latest version of the plugin, 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.
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 Slack for example URL"), then share the URL in the #prj-Today-Migration-Plugin Slack channel.
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 ucf-wp Slack workspace.
Please provide as much detail and context as possible to justify the inclusion of your idea in the plugin. 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.
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 plugin'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 plugin. 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.
Adhering to the following process is the best way to submit a pull request:
-
Fork the project.
-
Clone your fork, and configure the remotes:
# Clone your fork of the repo into the current directory git clone https://github.com/<your-username>/Today-Migration-Plugin.git # Navigate to the newly cloned directory cd Today-Migration-Plugin # Assign the original repo to a remote called "upstream" git remote add upstream https://github.com/UCF/Today-Migration-Plugin.git
-
If you cloned a while ago, get the latest changes from upstream:
git checkout master git pull upstream master
-
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 ofmaster
directly if norc-*
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 fromdevelop
will not be merged into the project. -
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)
Additionally, make sure that any changes to the README are made in
README.txt
, NOTREADME.md
. TheREADME.md
file is generated automatically via thegulp readme
task. If you have any README updates to include with your changes, please make sure to rungulp readme
so that both files get updated. -
Locally merge the upstream
rc-*
ormaster
branch (whichever you branched off of initially) into your topic branch:git merge --no-ff upstream master
-
Push your topic branch up to your fork:
git push origin <topic-branch-name>
-
Open a Pull Request against the
rc-*
ormaster
branch (whichever you initially branched off of.) Pull request titles and descriptions should be as descriptive and clear as possible.
In general, we keep conversations about distributed UCF WordPress projects on the ucf-wp Slack workspace. This workspace is owned and managed by UCF Web Communications (Webcom). You'll need a @ucf.edu email address to join.
Whenever you post to the ucf-wp Slack, including your job title, information about the college or department you work for, as well as the site(s) you need help with will help us help you more effectively.
If you have a general question about the plugin, design decisions, or any other question that isn't a help request, please post it in the #prj-Today-Migration-Plugin Slack channel.
If you need help with using this plugin 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-plugins Slack channel. You don't need to @mention anyone specific, but please note that you're using the Today Migration Plugin when posting your question and include a link to your site if it's relevant to your question.
Whenever you add or modify code in this repo, please follow the code style guides noted below, per language:
Adhere to the WordPress PHP Coding Standards for new or modified code.
- 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.
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.
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.