{"id":12,"date":"2023-09-01T21:47:50","date_gmt":"2023-09-01T21:47:50","guid":{"rendered":"\/\/contribute.jquery.org\/?page_id=12"},"modified":"2024-04-01T19:58:53","modified_gmt":"2024-04-01T19:58:53","slug":"commits-and-pull-requests","status":"publish","type":"page","link":"https:\/\/contribute.jquery.org\/commits-and-pull-requests\/","title":{"rendered":"Commits and Pull Requests"},"content":{"rendered":"<ul>\n<li><a href=\"#working-with-a-fork\">Working With a Fork<\/a><\/li>\n<li><a href=\"#never-commit-on-master\">Never Commit On Master<\/a><\/li>\n<li><a href=\"#branching\">Branching<\/a><\/li>\n<li><a href=\"#preparing-to-commit\">Preparing To Commit<\/a><\/li>\n<li><a href=\"#commit-guidelines\">Commit Guidelines<\/a><ul>\n<li><a href=\"#subject\">Subject<\/a><\/li>\n<li><a href=\"#long-description\">Long description<\/a><\/li>\n<li><a href=\"#references\">References<\/a><\/li>\n<\/ul>\n<\/li>\n<li><a href=\"#your-pull-request\">Your Pull Request<\/a><\/li>\n<\/ul>\n<p>We use git and GitHub's <a href=\"https:\/\/help.github.com\/articles\/using-pull-requests\">Pull Request<\/a> system to review and accept all contributions of code, content and design to all of our projects. Your experience can be as pleasant as possible (for everyone) if you follow these guidelines as you work on putting together the commits and pull requests that comprise your contributions.<\/p>\n<h2 class=\"toc-linked\" id=\"working-with-a-fork\"><a href=\"#working-with-a-fork\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Working With a Fork<\/h2><p>The first step to contributing fixes and improvements to any jQuery Foundation project is <a href=\"https:\/\/help.github.com\/articles\/fork-a-repo\">forking the repository<\/a> into your own GitHub account. Make sure to <a href=\"https:\/\/help.github.com\/articles\/fork-a-repo\">follow the instructions<\/a> on how to \"Configure Remotes\" and \"Pull in upstream changes\" -- you'll want to keep your fork in sync with changes that happen in the official repository.<\/p>\n<p><strong>If you didn't fork the repository initially and instead cloned it<\/strong> directly from the jQuery organization, but now find yourself wanting to submit a Pull Request, that situation is easily rectified. Fork the repo, then head to the clone directory on your local machine.<\/p>\n<div class=\"syntaxhighlighter javascript\">\n\t<table>\n\t\t<tbody>\n\t\t\t<tr>\n\t\t\t\t\n\t\t\t\t<td class=\"gutter\">\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n1\">1<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n2\">2<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n3\">3<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n4\">4<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n5\">5<\/div>\n\t\t\t\t\t\n\t\t\t\t<\/td>\n\t\t\t\t\n\t\t\t\t<td class=\"code\">\n\t\t\t\t\t<pre><div class=\"container\"><div class=\"line\"><code># Rename the original jQuery repo remote from 'origin' to 'upstream'<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>$ git remote rename origin upstream<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code> <\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code># Add your fork as the 'origin' remote<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>$ git remote add origin https:\/\/github.com\/{your_username}\/jquery.git<\/code><\/div><\/div><\/pre>\n\t\t\t\t<\/td>\n\t\t\t<\/tr>\n\t\t<\/tbody>\n\t<\/table>\n<\/div>\n\n<h2 class=\"toc-linked\" id=\"never-commit-on-master\"><a href=\"#never-commit-on-master\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Never Commit On Master<\/h2><p>When you're working on a fork, you should always think of your <code>master<\/code> branch as a \"landing place\" for upstream changes. You should only ever make your commits to topic branches, and your own commits should only ever end up on <code>master<\/code> after they've been merged in upstream by a maintainer.<\/p>\n<p>This is really for your own convenience: it's easy for the maintainer of a project to accept your pull request from your master branch, but it's problematic for your fork when you want to pull the changes back and your master branch has diverged from upstream's master branch.<\/p>\n<p><strong>If you accidentally commit on master<\/strong>, it's not hard to fix things up. Assuming you've just made an errant commit on <code>master<\/code>:<\/p>\n<div class=\"syntaxhighlighter javascript\">\n\t<table>\n\t\t<tbody>\n\t\t\t<tr>\n\t\t\t\t\n\t\t\t\t<td class=\"gutter\">\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n1\">1<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n2\">2<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n3\">3<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n4\">4<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n5\">5<\/div>\n\t\t\t\t\t\n\t\t\t\t<\/td>\n\t\t\t\t\n\t\t\t\t<td class=\"code\">\n\t\t\t\t\t<pre><div class=\"container\"><div class=\"line\"><code># \"Backs up\" your commit, creating a topic branch<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>$ git branch fix-spelling-error<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code> <\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code># Reset your master branch to the same state as upstream\/master<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>$ git reset --hard upstream\/master<\/code><\/div><\/div><\/pre>\n\t\t\t\t<\/td>\n\t\t\t<\/tr>\n\t\t<\/tbody>\n\t<\/table>\n<\/div>\n\n<h2 class=\"toc-linked\" id=\"branching\"><a href=\"#branching\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Branching<\/h2><p>Since you should never be committing on master, all of your commits will need to be on branches. You can create branches on the command line, or you can <a href=\"https:\/\/github.com\/blog\/1377-create-and-delete-branches\">create branches on GitHub<\/a>.<\/p>\n<p>If your branch pertains to a particular issue, it's useful to <strong>name the branch with a reference to the issue number<\/strong>. For example:<\/p>\n<div class=\"syntaxhighlighter javascript\">\n\t<table>\n\t\t<tbody>\n\t\t\t<tr>\n\t\t\t\t\n\t\t\t\t<td class=\"gutter\">\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n1\">1<\/div>\n\t\t\t\t\t\n\t\t\t\t<\/td>\n\t\t\t\t\n\t\t\t\t<td class=\"code\">\n\t\t\t\t\t<pre><div class=\"container\"><div class=\"line\"><code>$ git checkout -b <span class=\"hljs-number\">151<\/span>-remove-build-artifact<\/code><\/div><\/div><\/pre>\n\t\t\t\t<\/td>\n\t\t\t<\/tr>\n\t\t<\/tbody>\n\t<\/table>\n<\/div>\n\n<h2 class=\"toc-linked\" id=\"preparing-to-commit\"><a href=\"#preparing-to-commit\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Preparing To Commit<\/h2><p>When you're ready to commit your changes, there are a few things you should do first. The first step is reviewing your changes by running <code>git diff<\/code>. GUI tools for git like <a href=\"http:\/\/www.git-tower.com\/\">Tower<\/a> and GitHub's desktop apps (<a href=\"https:\/\/mac.github.com\/\">Mac<\/a>, <a href=\"https:\/\/windows.github.com\/\">Windows<\/a>) provide especially nice interfaces for those who don't like viewing diffs in their terminal. If you're comfortable working in a terminal, but want more visual diffs, you may want to check out <a href=\"https:\/\/www.npmjs.org\/package\/pretty-diff\">pretty-diff<\/a>.<\/p>\n<p>When viewing the diff, check for problems like unrelated whitespace changes, improper indentation, trailing spaces, left over debug code, etc. If the project you're working on has unit tests or build steps, you must run them before committing to ensure that you haven't introduced any failures. Be sure to include new tests when fixing bugs or adding features.<\/p>\n<h2 class=\"toc-linked\" id=\"commit-guidelines\"><a href=\"#commit-guidelines\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Commit Guidelines<\/h2><p>Commits should be atomic. If three separate issues are being fixed (unless they are all fixed by one change), they need to be done as three separate commits. This also applies to whitespace changes, which should be done in their own commit. Whitespace commits should not include code or content changes. Accordingly, code change commits should not include whitespace changes (unless the whitespace changes are on the same lines as the code being changed).<\/p>\n<p>Commit messages should describe what changed, and reference the issue number if the commit closes or is associated with a particular issue. Commit messages for all jQuery projects should look like this:<\/p>\n<div class=\"syntaxhighlighter javascript\">\n\t<table>\n\t\t<tbody>\n\t\t\t<tr>\n\t\t\t\t\n\t\t\t\t<td class=\"gutter\">\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n1\">1<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n2\">2<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n3\">3<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n4\">4<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n5\">5<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n6\">6<\/div>\n\t\t\t\t\t\n\t\t\t\t\t\t<div class=\"line n7\">7<\/div>\n\t\t\t\t\t\n\t\t\t\t<\/td>\n\t\t\t\t\n\t\t\t\t<td class=\"code\">\n\t\t\t\t\t<pre><div class=\"container\"><div class=\"line\"><code>Component: Short Description<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code> <\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>Optional Long Description<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code> <\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>Fixes #xxx<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>Closes gh-yyy<\/code><\/div><\/div><div class=\"container\"><div class=\"line\"><code>Ref #zzz<\/code><\/div><\/div><\/pre>\n\t\t\t\t<\/td>\n\t\t\t<\/tr>\n\t\t<\/tbody>\n\t<\/table>\n<\/div>\n\n<p>Every commit must have a subject (the first line). Everything else is optional.<\/p>\n<h3 class=\"toc-linked\" id=\"subject\"><a href=\"#subject\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Subject<\/h3><p>This is the first line. It consists of a component, like \"Event\" or \"Autocomplete\". This line must be 72 characters or less. There should be no full stop (period) at the end.<\/p>\n<h3 class=\"toc-linked\" id=\"long-description\"><a href=\"#long-description\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Long description<\/h3><p>There are two line breaks between the subject and the long description. The description can have any length and formatting, like lists, but it must be hard-wrapped at 80 characters.<\/p>\n<h3 class=\"toc-linked\" id=\"references\"><a href=\"#references\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> References<\/h3><p>References to issues or pull requests go after the long description, each one on their own line.<\/p>\n<ul>\n<li><p>Use <strong>Fixes<\/strong> when the commit fixes an open issue.<\/p>\n<\/li>\n<li><p>Use <strong>Closes<\/strong> when the commit closes an open pull request.<\/p>\n<\/li>\n<li><p>Use <strong>Ref<\/strong> when referencing an issue or pull request that is already closed or should remain open. Examples include partial fixes and commits that add a test but not a fix.<\/p>\n<\/li>\n<li><p>Always use \"gh-xxx\" for GitHub issues and pull requests within the same repository. Use \"[user]\/[repo]#xxx\" when referencing an issue or pull request in another repository, e.g., \"Closes jquery\/jquery-ui#175\".<\/p>\n<\/li>\n<\/ul>\n<h2 class=\"toc-linked\" id=\"your-pull-request\"><a href=\"#your-pull-request\" class=\"icon-link toc-link\"><span class=\"visuallyhidden\">link<\/span><\/a> Your Pull Request<\/h2><p>When you're ready to have your changes reviewed for inclusion in the project, that's when you submit a <a href=\"https:\/\/help.github.com\/articles\/using-pull-requests\">pull request<\/a>. Start by pushing your topic branch to your fork and then using one of the several options in GitHub's interface to iniatiate the request.<\/p>\n<p>Unless you are making a rather minor change, it is generally a good idea to file an issue on the appropriate bug tracker, explaining your idea <strong>before<\/strong> writing code or submitting a PR, especially when introducing new features.<\/p>\n<p>You should think of your pull request as a request for a code review. The project maintainers may accept it immediately, ask questions and point out tweaks that need to be made, or reject it outright. (There's a reason it's called a pull request, not a pull demand.) The commits may be taken as-is, or the maintainer may see fit to fix up or squash the changes into fewer commits.<\/p>\n<p>If you push new commits to the branch from which you initiated the pull request, the pull request will automatically be updated. However, a notification is not sent for new commits, so it is a good idea to comment on the pull request notifying the maintainers that there are new commits.<\/p>","protected":false},"excerpt":{"rendered":"<p>Working With a Fork Never Commit On Master Branching Preparing To Commit Commit Guidelines Subject Long description References Your Pull Request We use git and GitHub&#8217;s Pull Request system to review and accept all contributions of code, content and design to all of our projects. Your experience can be as pleasant as possible (for everyone) &hellip; <a href=\"https:\/\/contribute.jquery.org\/commits-and-pull-requests\/\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"categories":[],"tags":[],"class_list":["post-12","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/pages\/12","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/comments?post=12"}],"version-history":[{"count":2,"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/pages\/12\/revisions"}],"predecessor-version":[{"id":52,"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/pages\/12\/revisions\/52"}],"wp:attachment":[{"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/media?parent=12"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/categories?post=12"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/contribute.jquery.org\/wp-json\/wp\/v2\/tags?post=12"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}