{"action":"created","comment":{"url":"https://api.github.com/repos/LLNL/spack/pulls/comments/77405271","id":77405271,"diff_hunk":"@@ -0,0 +1,247 @@\n+.. _contribution-guide:\n+\n+Contribution Guide\n+=====================\n+\n+This guide is intended for developers or administrators who want to\n+contribute a new package, feature, or bugfix to Spack.\n+It assumes that you have at least some familiarity with Git VCS and Github.\n+The guide will show a few examples of contributing workflow and discuss\n+the granularity of pull-requests (PRs).\n+\n+First, what is a PR? Quoting `Bitbucket's tutorials <https://www.atlassian.com/git/tutorials/making-a-pull-request/>`_:\n+\n+  Pull requests are a mechanism for a developer to notify team members that they have **completed a feature**.\n+  The pull request is more than just a notification—it’s a dedicated forum for discussing the proposed feature\n+\n+Important is completed feature, i.e. the changes one propose in a PR should\n+correspond to one feature/bugfix/extension/etc. One can create PRs with\n+changes relevant to different ideas, however reviewing such PRs becomes tedious\n+and error prone. If possible, try to follow the rule **one-PR-one-package/feature.**\n+\n+Spack uses a rough approximation of the `Git Flow <http://nvie.com/posts/a-successful-git-branching-model/>`_ branching\n+model. The develop branch contains the latest contributions, and master is\n+always tagged and points to the latest stable release. Thereby when you send\n+your request, make ``develop`` the destination branch on the\n+`Spack repository <https://github.com/LLNL/spack>`_.\n+\n+Let's assume that the current (patched) state of your fork of Spack is only\n+relevant to yourself. Now you come across a bug in a package or would like to\n+extend a package and contribute this fix to Spack. It is important that\n+whenever you change something that might be of importance upstream,\n+create a pull-request (PR) as soon as possible. Do not wait for weeks/months to\n+do this: a) you might forget why did you modified certain files; b) it could get\n+difficult to isolate this change into a stand-alone clean PR.\n+\n+Now let us discuss several approaches one may use to submit a PR while\n+also keeping your local version of Spack patched.\n+\n+\n+First approach (cherry-picking):\n+--------------------------------\n+\n+First approach is as follows.\n+You checkout your local develop branch which for the purpose of this guide\n+will be called ``develop_modified``:\n+\n+.. code-block:: console\n+\n+  $ git checkout develop_modified\n+\n+Let us assume that lines in files you will be modifying\n+are the same in `develop_modified` branch and upstream ``develop``.\n+Next edit files, make sure they work for you and create a commit\n+\n+.. code-block:: console\n+\n+  $ git add <files_to_be_commited>\n+  $ git commit -m <descriptive note about changes>\n+\n+Normally we prefer that commits pertaining to a package ``<package-name>``` have\n+a message ``<package-name>: descriptive message``. It is important to add\n+descriptive message so that others, who might be looking at your changes later\n+(in a year or maybe two), would understand the rationale behind.\n+\n+\n+Next we will create a branch off upstream's ``develop`` and copy this commit.\n+Before doing this, while still on your modified branch, get the hash of the\n+last commit\n+\n+.. code-block:: console\n+\n+  $ git log -1\n+\n+and copy-paste this ``<hash>`` to the buffer. Now switch to upstream's ``develop``,\n+make sure it's updated, checkout the new branch, apply the patch and push to\n+GitHub:\n+\n+.. code-block:: console\n+\n+  $ git checkout develop\n+  $ git pull upstream develop\n+  $ git checkout -b <descriptive_branch_name>\n+  $ git cherry-pick <hash>\n+  $ git push <your_origin> <descriptive_branch_name> -u\n+\n+Here we assume that local ``develop`` branch tracks upstream develop branch of\n+Spack. This is not a requirement and you could also do the same with remote\n+branches. Yet to some it is more convenient to have a local branch which\n+tracks upstream.\n+\n+Now you can create a PR from web-interface of GitHub. The net result is as\n+follows:\n+\n+#. You patched your local version of Spack and can use it further\n+#. You \"cherry-picked\" these changes in a stand-alone branch and submitted it\n+   as a PR upstream.\n+\n+\n+Should you have several commits to contribute, you could follow the same\n+procedure by getting hashes of all of them and cherry-picking to the PR branch.\n+This could get tedious and therefore there is another way:\n+\n+\n+Second approach:\n+----------------\n+\n+In the second approach we start from upstream ``develop`` (again assuming\n+that your local branch `develop` tracks upstream):\n+\n+.. code-block:: console\n+\n+  $ git checkout develop\n+  $ git pull upstream develop\n+  $ git checkout -b <descriptive_branch_name>\n+\n+Next edit a few files and create a few commits by\n+\n+.. code-block:: console\n+\n+  $ git add <files_to_be_part_of_the_commit>\n+  $ git commit -m <descriptive_message_of_this_particular_commit>\n+\n+Now you can push it to your fork and create a PR\n+\n+.. code-block:: console\n+\n+  $ git push <your_origin> <descriptive_branch_name> -u\n+\n+Most likely you would want to have those changes in your (modified) local\n+version of Spack. To that end you need to merge this branch\n+\n+.. code-block:: console\n+\n+  $ git checkout develop_modified\n+  $ git merge <descriptive_branch_name>\n+\n+The net result is similar to the first approach with a minor difference that\n+you would also merge upstream develop into you modified version in the last\n+step. Should this not be desirable, you have to follow the first approach.\n+\n+\n+\n+How to clean-up a branch by rewriting history:\n+-----------------------------------------------\n+\n+Sometimes you may end up on a branch which has a lot of commits, merges of\n+upstream branch and alike but it can't be rebased on ``develop`` due to a long\n+and convoluted history. If the current commits history is more of an experimental\n+nature and only the net result is important, you may rewrite the history.\n+To that end you need to first merge upstream `develop` and reset you branch to\n+it. So on the branch in question do:\n+\n+.. code-block:: console\n+\n+   $ git merge develop\n+   $ git reset develop\n+\n+At this point you your branch will point to the same commit as develop and\n+thereby the two are indistinguishable. However, all the files which were\n+previously modified will stay as such. In other words, you do not loose the","path":"lib/spack/docs/contribution_guide.rst","position":160,"original_position":160,"commit_id":"73f6dc5b28b47f66dee949a724f72e2213842bed","original_commit_id":"73f6dc5b28b47f66dee949a724f72e2213842bed","user":{"login":"citibeth","id":1924215,"avatar_url":"https://avatars.githubusercontent.com/u/1924215?v=3","gravatar_id":"","url":"https://api.github.com/users/citibeth","html_url":"https://github.com/citibeth","followers_url":"https://api.github.com/users/citibeth/followers","following_url":"https://api.github.com/users/citibeth/following{/other_user}","gists_url":"https://api.github.com/users/citibeth/gists{/gist_id}","starred_url":"https://api.github.com/users/citibeth/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/citibeth/subscriptions","organizations_url":"https://api.github.com/users/citibeth/orgs","repos_url":"https://api.github.com/users/citibeth/repos","events_url":"https://api.github.com/users/citibeth/events{/privacy}","received_events_url":"https://api.github.com/users/citibeth/received_events","type":"User","site_admin":false},"body":"Change which -> that","created_at":"2016-09-02T20:12:16Z","updated_at":"2016-09-02T20:12:16Z","html_url":"https://github.com/LLNL/spack/pull/1664#discussion_r77405271","pull_request_url":"https://api.github.com/repos/LLNL/spack/pulls/1664","_links":{"self":{"href":"https://api.github.com/repos/LLNL/spack/pulls/comments/77405271"},"html":{"href":"https://github.com/LLNL/spack/pull/1664#discussion_r77405271"},"pull_request":{"href":"https://api.github.com/repos/LLNL/spack/pulls/1664"}}},"pull_request":{"url":"https://api.github.com/repos/LLNL/spack/pulls/1664","id":83212199,"html_url":"https://github.com/LLNL/spack/pull/1664","diff_url":"https://github.com/LLNL/spack/pull/1664.diff","patch_url":"https://github.com/LLNL/spack/pull/1664.patch","issue_url":"https://api.github.com/repos/LLNL/spack/issues/1664","number":1664,"state":"open","locked":false,"title":"add contribution guide focused on Git and PRs","user":{"login":"davydden","id":8023934,"avatar_url":"https://avatars.githubusercontent.com/u/8023934?v=3","gravatar_id":"","url":"https://api.github.com/users/davydden","html_url":"https://github.com/davydden","followers_url":"https://api.github.com/users/davydden/followers","following_url":"https://api.github.com/users/davydden/following{/other_user}","gists_url":"https://api.github.com/users/davydden/gists{/gist_id}","starred_url":"https://api.github.com/users/davydden/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/davydden/subscriptions","organizations_url":"https://api.github.com/users/davydden/orgs","repos_url":"https://api.github.com/users/davydden/repos","events_url":"https://api.github.com/users/davydden/events{/privacy}","received_events_url":"https://api.github.com/users/davydden/received_events","type":"User","site_admin":false},"body":"with the reference to https://groups.google.com/forum/?fromgroups#!topic/spack/2Rs3BMLeTFk\r\n\r\n~~p.s. anyone knows how to visualize changes in `atom`? Markdown preview does not follow the same rules...~~","created_at":"2016-08-30T05:55:03Z","updated_at":"2016-09-02T20:12:16Z","closed_at":null,"merged_at":null,"merge_commit_sha":"7607fe61b7804d545f20df235674dac16e02e46b","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/LLNL/spack/pulls/1664/commits","review_comments_url":"https://api.github.com/repos/LLNL/spack/pulls/1664/comments","review_comment_url":"https://api.github.com/repos/LLNL/spack/pulls/comments{/number}","comments_url":"https://api.github.com/repos/LLNL/spack/issues/1664/comments","statuses_url":"https://api.github.com/repos/LLNL/spack/statuses/73f6dc5b28b47f66dee949a724f72e2213842bed","head":{"label":"davydden:doc/contribution_git","ref":"doc/contribution_git","sha":"73f6dc5b28b47f66dee949a724f72e2213842bed","user":{"login":"davydden","id":8023934,"avatar_url":"https://avatars.githubusercontent.com/u/8023934?v=3","gravatar_id":"","url":"https://api.github.com/users/davydden","html_url":"https://github.com/davydden","followers_url":"https://api.github.com/users/davydden/followers","following_url":"https://api.github.com/users/davydden/following{/other_user}","gists_url":"https://api.github.com/users/davydden/gists{/gist_id}","starred_url":"https://api.github.com/users/davydden/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/davydden/subscriptions","organizations_url":"https://api.github.com/users/davydden/orgs","repos_url":"https://api.github.com/users/davydden/repos","events_url":"https://api.github.com/users/davydden/events{/privacy}","received_events_url":"https://api.github.com/users/davydden/received_events","type":"User","site_admin":false},"repo":{"id":54197262,"name":"spack","full_name":"davydden/spack","owner":{"login":"davydden","id":8023934,"avatar_url":"https://avatars.githubusercontent.com/u/8023934?v=3","gravatar_id":"","url":"https://api.github.com/users/davydden","html_url":"https://github.com/davydden","followers_url":"https://api.github.com/users/davydden/followers","following_url":"https://api.github.com/users/davydden/following{/other_user}","gists_url":"https://api.github.com/users/davydden/gists{/gist_id}","starred_url":"https://api.github.com/users/davydden/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/davydden/subscriptions","organizations_url":"https://api.github.com/users/davydden/orgs","repos_url":"https://api.github.com/users/davydden/repos","events_url":"https://api.github.com/users/davydden/events{/privacy}","received_events_url":"https://api.github.com/users/davydden/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/davydden/spack","description":"A flexible package manager designed to support multiple versions, configurations, platforms, and compilers.","fork":true,"url":"https://api.github.com/repos/davydden/spack","forks_url":"https://api.github.com/repos/davydden/spack/forks","keys_url":"https://api.github.com/repos/davydden/spack/keys{/key_id}","collaborators_url":"https://api.github.com/repos/davydden/spack/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/davydden/spack/teams","hooks_url":"https://api.github.com/repos/davydden/spack/hooks","issue_events_url":"https://api.github.com/repos/davydden/spack/issues/events{/number}","events_url":"https://api.github.com/repos/davydden/spack/events","assignees_url":"https://api.github.com/repos/davydden/spack/assignees{/user}","branches_url":"https://api.github.com/repos/davydden/spack/branches{/branch}","tags_url":"https://api.github.com/repos/davydden/spack/tags","blobs_url":"https://api.github.com/repos/davydden/spack/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/davydden/spack/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/davydden/spack/git/refs{/sha}","trees_url":"https://api.github.com/repos/davydden/spack/git/trees{/sha}","statuses_url":"https://api.github.com/repos/davydden/spack/statuses/{sha}","languages_url":"https://api.github.com/repos/davydden/spack/languages","stargazers_url":"https://api.github.com/repos/davydden/spack/stargazers","contributors_url":"https://api.github.com/repos/davydden/spack/contributors","subscribers_url":"https://api.github.com/repos/davydden/spack/subscribers","subscription_url":"https://api.github.com/repos/davydden/spack/subscription","commits_url":"https://api.github.com/repos/davydden/spack/commits{/sha}","git_commits_url":"https://api.github.com/repos/davydden/spack/git/commits{/sha}","comments_url":"https://api.github.com/repos/davydden/spack/comments{/number}","issue_comment_url":"https://api.github.com/repos/davydden/spack/issues/comments{/number}","contents_url":"https://api.github.com/repos/davydden/spack/contents/{+path}","compare_url":"https://api.github.com/repos/davydden/spack/compare/{base}...{head}","merges_url":"https://api.github.com/repos/davydden/spack/merges","archive_url":"https://api.github.com/repos/davydden/spack/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/davydden/spack/downloads","issues_url":"https://api.github.com/repos/davydden/spack/issues{/number}","pulls_url":"https://api.github.com/repos/davydden/spack/pulls{/number}","milestones_url":"https://api.github.com/repos/davydden/spack/milestones{/number}","notifications_url":"https://api.github.com/repos/davydden/spack/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/davydden/spack/labels{/name}","releases_url":"https://api.github.com/repos/davydden/spack/releases{/id}","deployments_url":"https://api.github.com/repos/davydden/spack/deployments","created_at":"2016-03-18T11:46:21Z","updated_at":"2016-03-18T11:46:22Z","pushed_at":"2016-09-02T14:59:47Z","git_url":"git://github.com/davydden/spack.git","ssh_url":"git@github.com:davydden/spack.git","clone_url":"https://github.com/davydden/spack.git","svn_url":"https://github.com/davydden/spack","homepage":"http://software.llnl.gov/spack","size":10568,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"develop"}},"base":{"label":"LLNL:develop","ref":"develop","sha":"bf8413379f479ab263748bddd4088b0968777e89","user":{"login":"LLNL","id":5921419,"avatar_url":"https://avatars.githubusercontent.com/u/5921419?v=3","gravatar_id":"","url":"https://api.github.com/users/LLNL","html_url":"https://github.com/LLNL","followers_url":"https://api.github.com/users/LLNL/followers","following_url":"https://api.github.com/users/LLNL/following{/other_user}","gists_url":"https://api.github.com/users/LLNL/gists{/gist_id}","starred_url":"https://api.github.com/users/LLNL/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/LLNL/subscriptions","organizations_url":"https://api.github.com/users/LLNL/orgs","repos_url":"https://api.github.com/users/LLNL/repos","events_url":"https://api.github.com/users/LLNL/events{/privacy}","received_events_url":"https://api.github.com/users/LLNL/received_events","type":"Organization","site_admin":false},"repo":{"id":15730865,"name":"spack","full_name":"LLNL/spack","owner":{"login":"LLNL","id":5921419,"avatar_url":"https://avatars.githubusercontent.com/u/5921419?v=3","gravatar_id":"","url":"https://api.github.com/users/LLNL","html_url":"https://github.com/LLNL","followers_url":"https://api.github.com/users/LLNL/followers","following_url":"https://api.github.com/users/LLNL/following{/other_user}","gists_url":"https://api.github.com/users/LLNL/gists{/gist_id}","starred_url":"https://api.github.com/users/LLNL/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/LLNL/subscriptions","organizations_url":"https://api.github.com/users/LLNL/orgs","repos_url":"https://api.github.com/users/LLNL/repos","events_url":"https://api.github.com/users/LLNL/events{/privacy}","received_events_url":"https://api.github.com/users/LLNL/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/LLNL/spack","description":"A flexible package manager designed to support multiple versions, configurations, platforms, and compilers.","fork":false,"url":"https://api.github.com/repos/LLNL/spack","forks_url":"https://api.github.com/repos/LLNL/spack/forks","keys_url":"https://api.github.com/repos/LLNL/spack/keys{/key_id}","collaborators_url":"https://api.github.com/repos/LLNL/spack/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/LLNL/spack/teams","hooks_url":"https://api.github.com/repos/LLNL/spack/hooks","issue_events_url":"https://api.github.com/repos/LLNL/spack/issues/events{/number}","events_url":"https://api.github.com/repos/LLNL/spack/events","assignees_url":"https://api.github.com/repos/LLNL/spack/assignees{/user}","branches_url":"https://api.github.com/repos/LLNL/spack/branches{/branch}","tags_url":"https://api.github.com/repos/LLNL/spack/tags","blobs_url":"https://api.github.com/repos/LLNL/spack/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/LLNL/spack/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/LLNL/spack/git/refs{/sha}","trees_url":"https://api.github.com/repos/LLNL/spack/git/trees{/sha}","statuses_url":"https://api.github.com/repos/LLNL/spack/statuses/{sha}","languages_url":"https://api.github.com/repos/LLNL/spack/languages","stargazers_url":"https://api.github.com/repos/LLNL/spack/stargazers","contributors_url":"https://api.github.com/repos/LLNL/spack/contributors","subscribers_url":"https://api.github.com/repos/LLNL/spack/subscribers","subscription_url":"https://api.github.com/repos/LLNL/spack/subscription","commits_url":"https://api.github.com/repos/LLNL/spack/commits{/sha}","git_commits_url":"https://api.github.com/repos/LLNL/spack/git/commits{/sha}","comments_url":"https://api.github.com/repos/LLNL/spack/comments{/number}","issue_comment_url":"https://api.github.com/repos/LLNL/spack/issues/comments{/number}","contents_url":"https://api.github.com/repos/LLNL/spack/contents/{+path}","compare_url":"https://api.github.com/repos/LLNL/spack/compare/{base}...{head}","merges_url":"https://api.github.com/repos/LLNL/spack/merges","archive_url":"https://api.github.com/repos/LLNL/spack/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/LLNL/spack/downloads","issues_url":"https://api.github.com/repos/LLNL/spack/issues{/number}","pulls_url":"https://api.github.com/repos/LLNL/spack/pulls{/number}","milestones_url":"https://api.github.com/repos/LLNL/spack/milestones{/number}","notifications_url":"https://api.github.com/repos/LLNL/spack/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/LLNL/spack/labels{/name}","releases_url":"https://api.github.com/repos/LLNL/spack/releases{/id}","deployments_url":"https://api.github.com/repos/LLNL/spack/deployments","created_at":"2014-01-08T09:22:12Z","updated_at":"2016-08-30T23:08:01Z","pushed_at":"2016-09-02T19:54:12Z","git_url":"git://github.com/LLNL/spack.git","ssh_url":"git@github.com:LLNL/spack.git","clone_url":"https://github.com/LLNL/spack.git","svn_url":"https://github.com/LLNL/spack","homepage":"http://software.llnl.gov/spack","size":18529,"stargazers_count":149,"watchers_count":149,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":133,"mirror_url":null,"open_issues_count":335,"forks":133,"open_issues":335,"watchers":149,"default_branch":"develop"}},"_links":{"self":{"href":"https://api.github.com/repos/LLNL/spack/pulls/1664"},"html":{"href":"https://github.com/LLNL/spack/pull/1664"},"issue":{"href":"https://api.github.com/repos/LLNL/spack/issues/1664"},"comments":{"href":"https://api.github.com/repos/LLNL/spack/issues/1664/comments"},"review_comments":{"href":"https://api.github.com/repos/LLNL/spack/pulls/1664/comments"},"review_comment":{"href":"https://api.github.com/repos/LLNL/spack/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/LLNL/spack/pulls/1664/commits"},"statuses":{"href":"https://api.github.com/repos/LLNL/spack/statuses/73f6dc5b28b47f66dee949a724f72e2213842bed"}}}}
{"actor":{"display_login":"citibeth"}}