Workspace - Revision history

Dan: Remove temp content

2019-05-16T15:10:45Z

Remove temp content

Show changes

Crogers at 22:03, 15 May 2019

2019-05-15T22:03:05Z

Dan: /* Make changes and commit them to your fork */ Add admonition about GitHub email settings.

2019-05-15T21:56:29Z

‎Make changes and commit them to your fork: Add admonition about GitHub email settings.

Dan: /* Keep your fork up to date */

2019-05-15T20:19:56Z

‎Keep your fork up to date

Dan: /* Contributing documentation using Vagrant */

2019-05-14T21:51:32Z

‎Contributing documentation using Vagrant

Dan: /* Contributing documentation using Vagrant */

2019-05-14T21:50:05Z

‎Contributing documentation using Vagrant

Dan: /* Open a pull request */

2019-05-14T21:49:11Z

‎Open a pull request

Dan: /* Troubleshooting */

2019-05-14T20:29:01Z

‎Troubleshooting

Dan: /* Troubleshooting */

2019-05-14T20:24:33Z

‎Troubleshooting

Dan: /* Troubleshooting */

2019-05-14T20:24:21Z

‎Troubleshooting

← Older revision		Revision as of 22:03, 15 May 2019
Line 290:		Line 290:

	Keep a password-protected copy of your key somewhere secure on your local computer. Make sure the private key password is unique and secure!		Keep a password-protected copy of your key somewhere secure on your local computer. Make sure the private key password is unique and secure!
		+
		+	'''Your process for starting up your Vagrant box'''
		+
		+	Using your command line interface, navigate to the folder where you have initialized your Vagrant box. Check to see if your SSH key is loaded by typing <code>ssh-add -l</code>. If it is, you can now run <code>vagrant up</code>. If it is not, you can load it with <code>ssh add</code>, or if you have more than one SSH key, to ensure you load the right key, <code>ssh add ~/.ssh/id_rsa</code>, where '~/.ssh/id_rsa' is the file path to your SSH key.
		+
		+	When your key is loaded, you can run <code>vagrant ssh -- -A</code> to SSH into the Vagrant environment with your own key. This will allow you to link to your github account.
		+
		+	<admonition type="note">
		+	If you run <code>vagrant ssh</code> you will access the Vagrant environment as the generic user 'vagrant', and any commits you make will be attributed to 'vagrant' and not to you.
		+	</admonition>
		+
		+	Once you are connected to the Vagrant environment, you can access the atom-docs with <code>cd atom-docs</code>, and continue from [https://wiki.accesstomemory.org/Workspace#Fork_the_AtoM_documentation_project Fork the AtoM project].

	====SSH keys - Windows users====		====SSH keys - Windows users====

@@ Line 571: / Line 571: @@
 * You can add a commit title without a description by using <code>git commit -m "your message here"</code>. If you just enter "git commit", you will be taken to a separate edit screen where you can add both a title and a longer description
 * When all the files in your local staging area have been committed, you can push them to your GitHub repository with <code>git push</code>
 Congrats! You're now ready to open a pull request against the public AtoM documentation!

@@ Line 602: / Line 602: @@
 <pre>
 git checkout 2.6
 git rebase upstream/2.6
 </pre>

@@ Line 259: / Line 259: @@
 * [[#Add the files to your local text editor|Add the files to your local text editor]]
 * [[#Make changes and commit them to your fork|Make changes and commit them to your fork]]
-* [[#Keeping your fork up to date|Keeping your fork up to date]]
+* [[#Keep your fork up to date|Keep your fork up to date]]
 * [[#Open a pull request|Open a pull request]]
 * [[#Add fixes and squash your commits|Add fixes and squash your commits]]
@@ Line 574: / Line 574: @@
 Congrats! You're now ready to open a pull request against the public AtoM documentation!
-===Keeping your fork up to date===
+===Keep your fork up to date===
 If you've been working in your local version of the documentation for a while, it's possible that there are new changes in the public documentation repository that you don't yet have. Before we open a pull request, we should make sure that your local fork is up to date.

@@ Line 261: / Line 261: @@
 * [[#Keeping your fork up to date|Keeping your fork up to date]]
 * [[#Open a pull request|Open a pull request]]
 ===Generate an SSH key and configure a forwarding agent===

← Older revision		Revision as of 21:49, 14 May 2019
Line 667:		Line 667:

	Our team will be notified once you've submitted your pull request - we'll review the work, and if we have questions or feedback, we'll post comments directly on the pull request. Make sure GitHub account settings are configured to notify you of changes, so you can follow up!		Our team will be notified once you've submitted your pull request - we'll review the work, and if we have questions or feedback, we'll post comments directly on the pull request. Make sure GitHub account settings are configured to notify you of changes, so you can follow up!
		+
		+	===Add fixes and squash your commits===
		+
		+	Once you've submitted your pull request, the Artefactual team will review the changes. If there's a problem, we can send you a message via GitHub, or even [https://help.github.com/articles/using-pull-requests/#pull-request-discussion begin a discussion right on the code!] This way, if there's something we don't understand about the changes you've made, we can connect with you directly. This is very similar to the code review process we undertake on code submissions from developers - see our [[Development/Code review\|Code review]] wiki page for more information.
		+
		+	You'll be able to see a summary of our changes and the status of the review on your pull request. We'll add comments if we have changes to request.
		+
		+	If you need to make changes, you can simply return to the files and edit them in place. Follow the same steps as above - when you push a new commit, GitHub should automatically include it as part of your pull request. You can also reply on the PR comments thread to ask for clarification or help, or to let us know that the requested changes have been implemented.
		+
		+	[[File:git-pull-respond.png\|center\|600px\|frameless\|An image of the comments thread as seen on a pull request in GitHub]]
		+
		+	====Squashing commits====
		+
		+	In some cases, we may request that you squash your commits when you update your PR, to keep the commit history clean and easy to understand.
		+
		+	<admonition type="tip">
		+	'''What does squashing mean in git?'''
		+
		+	The term squashing refers to consolidating multiple commits into one single commit, for the purpose of simplifying the project history. When there are many small commits, including minor revisions to previous work, a lot of the commit history is only relevant for the developer who generated it, so it's considered best practice to simplify this before submitting your work to a shared repository. Git provides users with the ability to rewrite the history of a commit for cases such as this - so squashing in this context refers to moving the changes introduced in one commit into its parent, so that you end up with one commit out of two or more.
		+
		+	For more general information on this topic, see the following chapter in the Git Book:
		+
		+	* [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History Git Tools: Rewriting History]
		+	</admonition>
		+
		+	There are several ways that you can do this in git, but our preferred method is to use git's interactive rebase. To do so:
		+
		+	'''1.''' Run git rebase using interactive mode. The numeric value after our <code>HEAD</code> variable in the following command tells git how many commits we want to fetch. For example, if your pull request currently includes 4 commits (of which the first contains the body of your work, and the next three are minor corrections), then we can see all of these commits using <code>4</code> as the variable, like so:
		+
		+	<pre>
		+	git rebase -i HEAD~4
		+	</pre>
		+
		+	This should display something similar to the following output:
		+
		+	<pre>
		+	pick d2c53e5 Update CSV import docs, fixes #50
		+	pick efaf92d Fix a typo in CSV import rewrite
		+	pick 5bc533c Add another section to the rewrite
		+	pick 3d304f2 Another minor formatting fix
		+
		+	# Rebase d2c53e5...3d304f2 onto 609f966 (4 commands)
		+	#
		+	# Commands:
		+	# p, pick = use commit
		+	# r, reword = use commit, but edit the commit message
		+	# e, edit = use commit, but stop for amending
		+	# s, squash = use commit, but meld into previous commit
		+	# f, fixup = like "squash", but discard this commit's log message
		+	# x, exec = run command (the rest of the line) using shell
		+	# d, drop = remove commit
		+	</pre>
		+
		+	<admonition type="note">
		+	Notice that there are 4 commits shown with the word <code>pick</code> next to them. If we ran the command using <code>HEAD~2</code>, this list would only include the 2 most recent commits. You can also show other unrelated commits (i.e. include more - <code>HEAD~8</code>) and simply leave them untouched in the following steps, if desired.
		+	</admonition>
		+
		+	What we're seeing above is a list of the last 4 commits for the repository. Note that it's in reverse order - the bottom commit is the most recent one. Instead of merging four commits, three of which are minor fixes to the first commit, it would be tidier to have one commit that included all those fixes. To squash them together, you'll need to decide which changes are minor (or fixups) - in this case, the 3 last commits. Let's change them so they will be squashed.
		+
		+	'''2.''' using our command-line text editor, we now want to edit the word "pick" before the 3 corrections, and change them to "fixup" - once saved, this tells git that these commits should be squashed into the first commit (still marked as "pick" - i.e. use this one), and their commit message discarded in favor of the original message associated with the commit you are keeping.
		+
		+	<admonition type="tip">
		+	When you were setting your global git identity, did you set your default preferred command-line text editor?
		+
		+	If not, odds are good that the default editor is vim - vim's commands can be pretty confusing if you are not used to them! Here are some tips:
		+
		+	* By default you are in "normal mode" - you can view, but not edit
		+	* Press <code>i</code> to enter insert mode, so you can make edits
		+	* Pressing <code>ESC</code> will return you to normal mode (not insert mode)
		+	* When you've made edits and then have returned to normal mode, press <code>:wq</code> to save and exit (write and quit)
		+	* You can quit ''without'' saving when in normal mode with <code>:q</code>
		+	* If you are reordering commits, <code>dd</code> in insert mode will cut the current line and copy it to the clipboard, and <code>P</code> will paste the clipboard content before the current line
		+
		+	You can read more about vim here:
		+
		+	* [https://vim.fandom.com/wiki/Tutorial vim Tutorial]
		+	* [https://vim.fandom.com/wiki/New_to_Vim New to vim]
		+	* [https://vimhelp.org/vim_faq.txt.html vim FAQ]
		+	</admonition>
		+
		+	Once you've made the necessary changes, save them and exit the editor:
		+
		+	* In vi or vim, use ESC to ensure you are in normal mode, then enter <code>:wq</code> to save and exit
		+	* In nano, use <code>CTRL+o</code>, press enter, and then <code>CTRL+x</code>
		+
		+	'''3.''' Before we proceed, let's confirm we've done this correctly. Run the command: <code>git log -1</code> to show the latest commit - it shoudl be the main commit you want to keep, and not any of the smaller fixes we marked with fixup. It should look something like this:
		+
		+	<pre>
		+	commit d2c53e548e339acdd5e1c3e2762347d1562b195f
		+	Author: username <email@example.com>
		+	Date: Wed Nov 14 15:54:08 2018 -0700
		+
		+	Update CSV import docs, fixes #50
		+	</pre>
		+
		+	If it's not, you can run <code>git log</code> to see a full list of all commits, and figure out what you missed. Repeat the steps above as needed.
		+
		+	'''4.''' Once you've successfully squashed your commits, we'll force push the fixed-up commit:
		+
		+	<pre>
		+	git push -f
		+	</pre>
		+
		+	Success!
		+
		+	===Celebrate===
		+
		+	You did it! Thank you for contributing to the AtoM documentation!
		+
		+	Once we've accepted the pull request and merged it into our repository, you'll get a notification (you'll probably get an email too, unless you've changed your default GitHub account settings). You'll be able to see the status of any changes right on the pull request.
		+
		+	It's time to dance!

	==Questions?==		==Questions?==

@@ Line 640: / Line 640: @@
 <admonition type="warning">
-BE CAREFUL: THIS WILL DELETE ALL LOCAL CHANGES YOU HAVE MADE!
+'''BE CAREFUL: THIS WILL DELETE ALL LOCAL CHANGES YOU HAVE MADE!'''
 </admonition>

@@ Line 625: / Line 625: @@
 <pre>
 git stash
-git rebase upstream/2.5
+git rebase upstream/2.6
 git stash pop
 </pre>

@@ Line 608: / Line 608: @@
 <pre>
-git rebase upstream/2.5
+git rebase upstream/2.6
 Cannot rebase: You have unstaged changes.
 Please commit or stash them.
@@ Line 617: / Line 617: @@
 <pre>
 git commit -a
 git push
 </pre>