<?php
// Include the config file first
include_once("../includes/config.inc.php");

// Set the page variables
$page_title = "Git Collaboration Workflow";
$page_description = "The guidelines for using Git to collaborate on this project.";
$page_author = "Niall";

// Then include the header (it will use the page variables above)
include_once("../includes/header.inc.php");
?>

	    	<!-- Beginning of blog post -->
	    	<div class="blog-post">
	    		<h2 class="blog-post-title">Git Collaboration Workflow</h2>
	    	  	<p class="blog-post-meta">Sept 17, 2020 by Niall Kader</p>

	    	  	<p>This article demonstrates the workflow that we'll use to collaborate on this blog site project.</p>
	    	  	<hr>
	    	  	<h3>Cloning the Repository</h3>
	    	  	<p>
	    	  		I will need your BitBucket user names so that I can grant you WRITE access to the repository.
	    	  		Once I've set you up, you'll be able to clone the repository.
	    	  		Make sure that you are in the <b>doc root</b> directory when you clone it. 
	    	  		Run this command to clone the repository:
	    	  	</p>
	    	  	<pre class="language-html"><code>git clone https://niall_kader@bitbucket.org/wtc-student-site/student-blog-site.git</code></pre>
	    	  	<h3>Create Your Own Branch</h3>
	    	  	<p>
	    	  		To avoid conflicts, each student will create his/her own branch.
	    	  		When you use your own branch, you don't have to worry about other students making commits that could conflict with your own commits.
	    	  		You'll create a branch using <b>your first name and last initial</b>.
	    	  		So, for example, here's the command that I would run to create my own branch:
	    	  	</p>
	    	  	<pre class="language-html"><code>git branch niallk</code></pre>
	    	  	<p>
	    	  		You are currently working in the <b>master</b> branch, so you'll have to switch to your new branch by using the <b>git checkout</b> command.
	    	  		For example, here is how I would switch the branch I just created:
	    	  	</p>
	    	  	<pre class="language-html"><code>git checkout niallk</code></pre>
	    	  	<p>
	    	  		Now each student working on the project will have their very own branch, and we don't have to worry about stepping on each others toes (making changes that conflict with one another).
	    	  		All of the commits that you make now will affect your branch only.
	    	  	</p>
	    	  	<h3>Putting Your Blog Post Into the Project</h3>
	    	  	<p>
	    	  		Create a new .html file in the appropriate folder of the site (<b>note:</b> we have transitioned the site to PHP, so when you create a new blog post you'll actually be creating a .php page).
	    	  		Since everyone's first blog post is about JavaScript, you'll create a new file in the the JavaScript folder.
	    	  		Note that the name of the file should describe what the article is about. 
	    	  		So, if you write an article about JavaScript functions, you should name your file something like <b>javascript-functions.php</b>.
	    	  		File names for our web pages should be all lowercase letters and use dashes to separate words.
	    	  	</p>
	    	  	<p>
	    	  		I have created a template for all the pages that we add to this site, it's in the <b>templates</b> folder.
	    	  		When you add a new blog post to the site, you can use the template to get started.
	    	  		Copy the contents of the template into the file you just created.
	    	  		Then replace the 'dummy' content with the appropriate information, make sure to update the following:
	    	  	</p>
	    	  	<ul>
	    	  		<li>The TITLE element</li>
	    	  		<li>The META/Author and META/Description elements</li>
	    	  		<li>The blog post heading, which is an H2 element inside the MAIN element</li>
	    	  		<li>The date, and your name (as the author) within the MAIN element</li>
	    	  		<li>The brief description of the article, which is just under the date</li>
	    	  	</ul>
	    	  	<p>
	    	  		Now go ahead and put your blog post into the page.
	    	  		All of your content should be placed inside the DIV element that has a class attribute set to <b>blog-post</b>.
	    	  		If you include any images in your page, the image files should be put into the <b>images</b> folder.
	    	  	</p>
	    	  	<h3>
	    	  		Committing Your Blog Page
	    	  	</h3>
	    	  	<p>
	    	  		Make sure that you commit your changes every time you work on the project.
	    	  	</p>
	    	  	<pre class="language-html"><code>git add .
git commit -m "Put a message here"
git push origin yourbranchname</code></pre>
	
				<h3>The Review Process</h3>
				<p>
					Once you are done creating a blog post you'll want to merge it into the master branch.
					But we'll be using a review process to make sure that the blog post is production ready.
					It should be very well-written, interesting, and easy to follow. 
					The code samples in your post should be easy for readers to try out.
					The HTML code in the blog post should follow the template (in the template folder).
					So in order to ensure that your blog post meets these quality standards, one of your peers will review it before merging it into the master branch.
				</p>
				<h3>Creating a Pull Request</h3>
				<p>
					Once your blog page is finished you should create a <b>pull request</b> and specify one of your peers to review it.
					Here are the steps that you must follow to create a pull request:					
				</p>
				<ol>
					<li>Go to the repository page on BitBucket (you should see your repositories when you log in)</li>
					<li>Click on <b>Pull Requests</b> on the left</li>
					<li>Click on <b>Create Pull Request</b> (in the upper right corner)</li>
					<li>
						You want to request that <b>your branch</b> gets merged into the master branch.
						So the drop down on the left should be set to your branch, while the one on the right will be set to <b>master</b>.
					</li>
					<li>In the description box, make sure to add the name of the blog page that will be reviewed (you can enter a url, like so: <b>http://localhost/student-blog-site/Git/git-collaboration-work-flow.php</b>).</li>
					<li>
						Make sure to assign a reviewer (I will tell you who to assign it to).
					</li>
				</ol>
				<p>
					The reviewer will take a good look at all of the changes you made and either approve and merge, or decline the request.
					The review process will help to make sure that the master branch is free of errors.
				</p>
				<h3>Reviewing a Pull Request</h3>
				<p>
					If you are assigned to review a pull request to merge a branch into master, you'll want to have a look at that branch before you accept or decline the request.
					To do this, you can copy the branch to your computer and switch to it with the following two commands (make sure that you are running these commands from the project folder):
				</p>
				<pre class="language-html"><code>git fetch origin branchname
git checkout branchname</code></pre>
				<p>
					Then you can view the page in the browser to review it.
					Do an extremely good job of reviewing the page.
					We want only the highest quality content for this project!
					Make sure that the author also followed all the guidelines for the HTML code on the page (which are listed above).
					Finally, make sure that all code is formatted and indented properly (but remember that we have to break the rules of proper indentation when using PRE elements).
				</p>
				<p>
					Once you have reviewed the blog page, you'll follow these steps:
				</p>
				<ol>
					<li>
						Go to the BitBucket homepage for the repository and click on the link to <b>Pull requests</b>
					</li>
					<li>
						Find the pull request that was assigned to you and click on it (your initials will appear to the right of the pull request).
					</li>
					<li>
						You can add comments to the code in the blog page that you are reviewing to provide feedback to your peers.
						You should have some comments if you decide that the page does not meet our quality standards.
					</li>
					<li>
						Click the either the button to Merge or Decline the pull request.
					</li>
				</ol>
				<h3>Cleaning Up Your Local Repository After a Review</h3>
				<p>
					Once you've reviewed a peer's blog post, switch back into your branch and then remove their branch from your local computer.
					Make sure to switch back to your own branch first (you cannot delete a branch that you currently have checked out):
				</p>
				<pre class="language-html"><code>git checkout yourbranchname</code></pre>
				<p>
					To delete the branch, enter this command (use the correct branch name):
				</p>
				<pre class="language-html"><code>git branch -d branchname</code></pre>
				<h3>
					Merging Master Into Your Branch
				</h3>
				<p>
					You'll want to update your branch with the master branch periodically, so that you can get all the changes that other students have made.
					But before you do this, you need to make sure that you have your branch checked out (that you are working in your branch).
					Enter this command to look at all the branches on your local repository:
				</p>
				<pre class="language-html"><code>git branch</code></pre>
				<p>
					This will list all of the branches, and the one you are working in will have an asterisk next to it.
					If your branch does not have an asterisk next to it then you need to run this command:
				</p>
				<pre class="language-html"><code>git checkout yourbranchname</code></pre>
				<p>Now you can go ahead and merge the master branch into your own by running this command.</p>
				<pre class="language-language"><code>git pull origin master</code></pre>
				<p>
					This will fetch the master branch from BitBucket (which is the origin) and merge it into the branch that you are currently working in.
				</p>


	    	</div>
	    	<!-- End of blog post -->
<?php
include_once("../includes/footer.inc.php");
?>
