diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Clone the Repository.md b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Clone the Repository.md index 233a1af..3ced03e 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Clone the Repository.md +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Clone the Repository.md @@ -1,20 +1,20 @@ -You should remember from INFO201 that currently the Git repository only exists on the GitBucket server. We need to clone copy down to your home folder so that you can use it. +You should remember from INFO201 that currently the Git repository only exists on the GitBucket server. We need to clone a copy down to your home folder so that you can use it. 1. Start NetBeans 11 if you haven't already. 1. < Git > Clone">>. - Once you have a Git repository open the *Clone* item moves to the < Remote">> menu. + Once you have a Git repository open the <> item moves to the < Remote">> menu. If asked for a master password at this point (or any later point), it is 'password' (without the speech marks). 1. Switch to the GitBucket *quick setup* page in your web browser, and copy one of the *origin* URLs for your repository from the page. It will start with `https://` and end with `.git`. -1. Paste the URL into the *Repository URL* box in NetBeans. +1. Paste the URL into the <> box in NetBeans. 1. Enter your GitBucket username and password and check the save password check box. -1. Under the *Specify Destination Folder* section click <>. +1. Under the <> section click <>. Navigate to a location where you want to store your course project. If you have not done so already, you should create a folder named `info202` in the < Documents">> for storing your INFO202 coursework. @@ -24,8 +24,6 @@ Make sure that the <> checkbox is checked. This will cause NetBeans to offer to create a project the repository after it is cloned. - Pay attention to the directory that the repository folder is about to be placed in and then click <>. - 1. When NetBeans offers to create a project for you, check the <> checkbox so that we have the project added to the favorites pane, and click the <> button. Choose < Java Application">> @@ -33,3 +31,5 @@ 1. Name the project `info202_project`, and delete the <> (leave it blank). 1. Click Finish. + +You should see a project in the NetBeans projects pane that contains a class named `Main` in the default package. diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Code Snippets.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Code Snippets.tid deleted file mode 100644 index eac2c35..0000000 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Code Snippets.tid +++ /dev/null @@ -1,24 +0,0 @@ -created: 20200702091026430 -modified: 20200707005526287 -section: 4.1 -tags: lab02 -title: /Labs/02/Code Snippets -type: text/x-markdown - -You will regularly need to share code snippets and error messages when working with other people. Most Git server software like GitBucket (Snippets) and GitHub (Gists) have the ability to do this. - -1. Switch to GitBucket in your web browser. - -1. Click the <> button at the top of the page. - -1. Click <> to create a snippet. - -1. Enter some text into the large text area. You do not need to provide a description or file name. - -1. Click <>. *Secret* mode allows you to give the URL to other people and they will be able to see the code, but it will not be visible to other GitBucket users. *Private* mode means that only you can see it, and *Public* mode means that everyone can see it. - -1. Copy the URL in the browser's location bar. Open another tab using the browser's private/incognito mode, and paste the URL. You will need to log in to GitBucket again, since using private mode is pretty much the same as using an entirely different computer. You should be able to see your code. - -1. Delete your Snippet using the <> button. - -If you have error messages or stack traces that you want to share with staff, then please use the Snippets feature. We do not like receiving screenshots of text. If you send us a screenshot of text, then you may receive a reply in the form of a screenshot of an email message. diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Commit and Push.md b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Commit and Push.md index 976e8e3..c0c831e 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Commit and Push.md +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Commit and Push.md @@ -4,53 +4,58 @@ Select < Commit">>. - You will see a dialog appear showing you what files are going to be added to the repository. At this point it will just be the Gradle build script, and the `Main` class. + You will see a dialog appear showing you what files are going to be added to the repository. At this point it will just be the Gradle files, and the `Main` class. - You will also see a text area in which you can add a *Commit Message*. You should always provide a useful message -that describes what you have done since you last committed. In this case we have just created the initial project, so enter a message that describes that. + You will also see a text area in which you can add a *Commit Message*. You should always provide a useful message that describes what you have done since you last committed. A Git commit message is a bit like an email message. The first line represents the subject and should very briefly name the feature/bug you were working on and what action you were performing on that feature/bug (adding, fixing, refactoring, completing, ...). There should be a blank line after the first line. The rest of the message can include a more detailed description of *why* the commit was added. Note the use of the word 'why' rather than 'what' in the previous sentence. We can easily see what changed --- Git has many features that can show us what changed so we don't need to repeat this in the commit message. The commit message is about describing why those changes were made. + In this case, we have just created the project, so your commit message should reflect that. + Click <>. -1. You should see the Git log in the output pane. You will see a message at the end stating that the commit has finished. +1. You should see the Git log in the output pane. You will see a message at the end stating that the commit has finished. Since you are committing to the local repository in your home folder the commit should happen nearly instantly. - Since you are committing to the local repository in your home folder the commit should happen nearly instantly. - -1. Open the repository browser: < Repository > Repository Browser">>. +1. Open the repository browser using < Repository > Repository Browser">>. This is a handy browser that we can use to perform operations on the entire repository rather than just the NetBeans project. If you only have one project in the repository then there is little difference. However, we can have many projects inside a single repository. Some actions require you to use the repository browser. An example would be if you move a file from one project into another. Ideally you would commit that action in a single commit, so you would have to perform the commit on the repository rather than the projects. - We will use the repository browser to interact with GitBucket in the next step. + This is a handy pane to keep open. We will use the repository browser to interact with GitBucket in the next step. -1. At this point you have only added the files to your *local* repository. +1. At this point you have only added the files to your *local* repository. Now we need to *push* the local repository into the repository on GitBucket. - Now we need to *push* the local repository into the repository on GitBucket. - - Right click your repository in the repository browser. < Push to Upstream">>. + Right click your repository in the repository browser and select < Push to Upstream">>. You will be asked if you want to create a new remote *master* branch since the repository on GitBucket is currently empty. Click <>. - You will also be asked if you want the local master to track the remote master. Doing this makes it easy to compare the local version of the project against the remote version which is sometimes useful if you want to see what you have changed since you last pushed. Again click <>. + You will also be asked if you want the local master to track the remote master. Doing this makes it easy to compare the local version of the project against the remote version which allows you to see what you have changed since you last pushed. Again click <>. 1. Check the output pane. You should see a message stating that the push is finished. +1. In the repository browser, expand the <> and <> folders under <>. + + You will see that currently there is only one branch in the local repository --- `master`. This is the primary branch for most Git repositories --- most work will be added to this branch. + + You will also see that there is a remote branch named `origin/master`. This is a branch that is used to store a copy of the master that comes from GitBucket. When you pull, the `master` on GitBucket is copied into this branch. This allows you to compare between the local `master` and the remote `master` to see what has changed since your last push/merge. + + Since we told Git to make the local master track the remote master, you can see that the local `master` is automatically checking itself against the `origin/master`. At the moment both branches are `in sync` with each other, meaning they are both identical --- you can also see that both branches have the same commit ID for their most recent commits. + 1. Go back to the web browser and refresh the GitBucket repository page. You should now see that your repository has the NetBeans project in it. You will also see the commit message beside the files. -1. Drill into the project by clicking the project folder. Drill into the <> folder. You should see your `Main` class. +1. Explore the project by clicking the `info202_project` folder. Click the <> folder. You should see your `Main` class. The general rules for committing and pushing are: - * Commit after you have completed some kind of logical work unit. - - Examples could be: + * Commit after you have completed some kind of logical work unit. Examples could be: * You added a new feature, or at least completed some logical milestone on your way towards completing the feature. * You fixed a bug. + * You added a section to a documentation file. + * You completed some other milestone, such as finishing an important class, or completing an issue. One good way to think about logical work units is to think about the commit message that you would add when you complete the commit. If you can't think of anything to add that another developer working on the same project would find useful, then you might not be at a logical place to commit yet. @@ -59,10 +64,12 @@ Think of the commit messages as a development log for other developers (or yourself in a few weeks time after you have forgotten how/where you implemented some features). You or another developer should be able to use the commit messages to easily find the commits that added a particular feature, or fixed a particular bug. If this is not the case then you are doing it wrong and your Git history is useless. - If in doubt, committing more is better than committing less. Git has features that can be used to *squash* smaller commits into a larger commit. If you have 5 commits relating to a single feature you can later squash these commits into a single commit larger commit that contains the entire feature. This is often done prior to 'publishing' your work to team mates or to a public repository via a push. + If in doubt, committing more is better than committing less. Git has features that can be used to *squash* smaller commits into a larger commit. If you have 5 commits relating to a single feature, you can later squash these commits into a single larger commit that contains the entire feature. This is often done prior to 'publishing' your work to team mates or to a public repository via a push. * Note that committing and pushing are different operations. Committing modifies your local repository (the version in your home folder). Pushing will push the changes in your local repository to the remote repository (GitBucket). - You don't have to push after every commit, but it is a good idea to push regularly so that you have a recent backup of your repository if something horrible happens. While not necessary, pushing after committing is a good habit to get into as a novice --- you are much less likely to accidentally turn your source trees into gorse bushes if you push after each commit. + Put another way, committing will update the local branch. Pushing will synchronise the local branch with the remote branch on the server. -* Before you log out and leave also make sure that you push so that you have the latest version of your code in GitBucket in case you want to download it and continue working on it from home. \ No newline at end of file + You don't have to push after every commit, but it is a good idea to push regularly so that you have a recent backup of your repository in case something horrible happens. + +* Before you log out and leave also make sure that you push so that you have the latest version of your code in GitBucket in case you want to continue working on it from home. \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Create the Product Domain Class.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Create the Product Domain Class.tid index 80a04dd..b39257a 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Create the Product Domain Class.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Create the Product Domain Class.tid @@ -9,11 +9,11 @@ {{/Labs/02/images/Project Domain Model}} -1. Create a new class that represents the product domain class. +1. Create a new class that represents the `Product` domain class. You use < New File > Java > Java Class">> to create a regular class. - Domain classes should be placed in a package named `domain`. + Domain classes should be placed in a package named `domain`. You can type the package name directly into the <> text field. Remember to stick to the naming conventions described in lab 1. Classes should start with an uppercase letter, and packages should be entirely lowercase. @@ -23,8 +23,6 @@ Remember that the industry convention for naming fields, methods, and variables in Java is to use a lowercase first letter. The only things that should start with an uppercase letter are type names (such as classes and interfaces). - Think about and use appropriate types for the fields. Price should be `BigDecimal` to help avoid approximation errors. Quantity should be either `Integer` or `BigDecimal` for the same reason. Using `BigDecimal` is a way of using decimal numbers safely (remember from COMP101 that floating point numbers are approximations). We will discuss this in more detail in lectures later in the course. - 1. Get NetBeans to insert getters and setters for these fields by using < Insert">>. 1. Add a `toString` method that returns the ID and name. You can use < Insert">> again to generate the method. @@ -40,9 +38,17 @@ ``` The hash character is important. The number relates to the issue number which you can see by viewing the issues on GitBucket. If you get this right then GitBucket will link between the commits and issues so that you can navigate from one to the other. This is quite powerful --- it allows you to see the commits (and the code that was changed by that commit) that relate to a particular issue. -1. Push. We are pushing now because we want to see the issue/commit integration on GitBucket. +1. Look at the branches in the repository browser again. We now have a commit that only resides in the local `master`. You can see the local `master` is `ahead` of the remote `origin/master`. The commit IDs for the most recent commits to each branch are also different. -1. Browse the issues on GitBucket. Click the title for issue \#1 to view the details. You should see the commits that have been associated with this issue. If you click the commit ID (the 7-digit ID on the right) you will see the code for this commit. + This is how you can tell if you need to push --- if your local branch is ahead of the remote branch then you have commits that need to be pushed. + +1. Push to upstream. We are pushing now because we want to see the issue/commit integration on GitBucket. + + Now is a good time to discuss *upstream* and *origin*. In most cases they are the same thing. Origin is the name that Git uses to represent the remote server that your cloned from. + + NetBeans uses the term *upstream* since you are able to have many remote servers attached to the same repository. NetBeans uses *upstream* to refer to whatever remote server you have set as the default remote --- in most cases it is the same as *origin*, but it doesn't have to be. + +1. Browse the issues for your repository on GitBucket. Click the title for issue \#1 to view the details. You should see the commits that have been associated with this issue. If you click the commit ID (the 7-digit ID on the right) you will see the code for this commit. This is a powerful combination. You can now easily answer questions from your team mates such as: @@ -52,12 +58,12 @@ * Did we remember to fix bug X? I feel like we might have accidentally closed the issue without ever getting around to it. - Look at the commits for issue X and see if any of them explicitly state 'Fixed bug X'. Then look at the code associated with those commits and triple check. + Look at the issue for X and see if any of the commit messages explicitly state 'Fixed bug X'. Then look at the code associated with those commits and triple check. - * Why did we implement feature Z in this weird way? + * Why did we implement feature Z this non-standard way? - Find the issue for Z. If your team is following good code review practices then there should be a comment thread associated with the issue that discusses the implementation. + Find the issue for Z. If your team is following good code review and documentation practices then there should be a comment thread associated with the issue that discusses/explains the reason for the non-standard implementation. We are only able to see the commits for an issue if we remember to reference the issue in the commit messages. Remember to do this! -When you come to create the other domain classes the commit messages for those should also reference this issue. +When you come to create the other domain classes, the commit messages for those should also reference this issue. \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Creating Your Project Git Repository.md b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Creating Your Project Git Repository.md index 5634860..b1f20bf 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Creating Your Project Git Repository.md +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Creating Your Project Git Repository.md @@ -1,16 +1,14 @@ -You will be working on the course project in the labs in INFO202. You need to create a GitBucket repository to host the work that you will be doing for this project. Let's do this now. +You will be working on the course project in the labs in INFO202. You need to create a GitBucket repository to host the work that you will be doing for this project. Let's do this now: -1. Log in to the GitBucket server using the details sent to you. - - You should bookmark the URL so that you can easily find it again. +1. Log in to the GitBucket server using the details sent to you. You should bookmark the URL so that you can easily find it again. 1. Click the *New repository* button. It is the <> icon in the top right of the page. -1. In the *Repository name* text field, enter the name of the repository. Use the name: `info202_project` +1. In the <> text field, enter the name of the repository. Use the name: `info202_project` -1. Check that the *Private* radio button is selected (this is the default anyway) to ensure that only you can access this repository (and the INFO202 teaching staff). +1. Check that the <> radio button is selected (this is the default anyway) to ensure that only you can access this repository (and the INFO202 teaching staff --- we all have administrator accounts on the GitBucket server, so we can access private repositories). -1. Leave the *Create an empty repository* option selected. We can add a README later if needed, and adding it at this point obscures the useful information that GitBucket displays for empty repositories. +1. Leave the <> option selected. We can add a README later if needed, and adding it at this point obscures the useful "quick setup" information that GitBucket displays for empty repositories. 1. Click the <> button. diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Git in a Team.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Git in a Team.tid index 92c26ff..d79b994 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Git in a Team.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Git in a Team.tid @@ -7,4 +7,4 @@ Until now you have primarily been using Git as a single developer. There are a few things that you should know in order to use Git effectively when working with other developers in a team. -Note that INFO202 coursework is all individual. This lab is about preparing your for third year courses, and the industry, where you will most probably be working with other people on a single code base. \ No newline at end of file +Note that INFO202 coursework is all individual. This lab is about preparing your for third year courses and the industry, where you will most probably be working with other people on a single project. \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Introduction.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Introduction.tid index de6bf23..88116fc 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Introduction.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Introduction.tid @@ -7,10 +7,8 @@ In this week's lab you will be: -* Creating your labs and project Git repositories. - -* Learning how to use Git in a team environment. +* Creating a Git repository for your course project. * Experimenting with Issue Driven Development. -* Using NetBeans to create basic graphical user interfaces (GUIs). \ No newline at end of file +* Learning how to use Git in a team environment. \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Issue Driven Development.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Issue Driven Development.tid index 6f7d204..ff1d9d1 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Issue Driven Development.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Issue Driven Development.tid @@ -7,18 +7,20 @@ We have mentioned *issue driven development* a few times. This is the idea of using an issue management system as a 'to do list' to drive your development. Issues help you to give your commits more context and make it easier for yourself and other developers to find the code for a particular feature or bug. Issues also help to form part of the documentation for the system, particularly since developers can add comments to issues to elaborate on decisions or provide clarification for problems and bugs. -Using issues is also a good way of ensuring that your commits make sense --- work on a single issue and then commit before starting on the next issue. If you do this then your commit history will be focused around your issues, and assuming your issues are based on features, bugs, and other logical work units (which they should be), then your commit history will make sense. +Using issues is also a good way of ensuring that your commits make sense --- work on a single issue and then commit before starting on the next issue. If you do this then your commit history will be focused around your issues, and assuming your issues are based on features, bugs, and other logical work units (which they should be), then your commit history will make sense, and will be useful to you and your team mates in the future. + +Let's create an issue: 1. On the GitBucket web page for your repository, click the <> link in the menu on the left. -Click the <> button on the right. + Click the <> button on the right. 1. One of the first things you will need to do in the course project is to create the domain classes. Add an issue with the title 'Create domain classes'. You can also add a description explaining which domain classes you will need (`Product`, `Customer`, `Sale`, and `SaleItem`). - Think of this issue as an item on your 'to do list'. It should have enough detail that it makes sense to you in several days/weeks time. + Think of this issue as an item on your 'to do list'. It should have enough detail that it should still make sense to you in several days/weeks time. When you are happy, click <>. -1. Click the <> menu item on the left again. This is effectively your to do list. +1. Click the <> menu item on the left again. This is effectively your to do list for this repository. -1. Add another issue to remind yourself to create a data entry form for the product domain class to allow users to enter the details for a product. + There is another <> link at the top of the page. This one will show you your issues for all of your repositories. diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Lab Attendance.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Lab Attendance.tid index bb921f6..8a5baa5 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Lab Attendance.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Lab Attendance.tid @@ -7,4 +7,4 @@ As described in the first lecture and the course outline, we have a terms requirement that requires you to attend 8 out of 11 labs (not including the first and last labs). -We will come around near the end of the lab to check you off. If you need to leave early, then please let Mark know so that you don't get missed. It is your responsibility to make sure that your attendance has been recorded before leaving the lab. \ No newline at end of file +We will come around near the end of the lab to check you off. If you need to leave early, then please let Mark or Chris know so that you don't get missed. It is your responsibility to make sure that your attendance has been recorded before leaving the lab. \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Project Work.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Project Work.tid index 9e8680f..d567328 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Project Work.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Project Work.tid @@ -13,4 +13,6 @@ * Implement the remaining classes in the domain model using the class diagram shown in section [3.1](#/Labs/02/Create%20the%20Product%20Domain%20Class). - Refer to the project document for the complete details for the domain model. This lab document only contains the class diagram --- the project document has more information in it. The project document will be released around the middle of the week. \ No newline at end of file + Refer to the project document for the complete details for the domain model. This lab document only contains the class diagram --- the project document has more information in it. The project document will be released around the middle of the week. + + Remeber to reference the issue that you created in section [3](#/Labs/02/Issue%20Driven%20Development) when committing these classes. \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Sharing Code Snippets.md b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Sharing Code Snippets.md new file mode 100644 index 0000000..2ace024 --- /dev/null +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Sharing Code Snippets.md @@ -0,0 +1,21 @@ +You will regularly need to share code snippets and error messages when working with other people. Most Git server software like GitBucket (Snippets) and GitHub (Gists) have the ability to do this. + +1. Switch to GitBucket in your web browser. + +1. Click the <> button at the top of the page. + +1. Click <> to create a snippet. + +1. Enter some text into the large text area. You do not need to provide a description or file name. + +1. Click <>. *Secret* mode allows you to give the URL to other people and they will be able to see the code, but it will not be visible to other GitBucket users. *Private* mode means that only you can see it, and *Public* mode means that everyone can see it. + +1. Copy the URL in the browser's location bar. Open another tab using the browser's private/incognito mode, and paste the URL. You will need to log in to GitBucket again, since using private mode is pretty much the same as using an entirely different computer. You should be able to see your code. + + You would share the URL with your team members so that they can view the snippet. + +1. Delete your Snippet using the <> button. + +If you have error messages or stack traces that you want to share with INFO202 teaching staff, then please use the Snippets feature. We do not like receiving screenshots of text. If you send us a screenshot of text, then you may receive a reply in the form of a blurry screenshot of an email message that chops off the right third of the message (that is pretty typical of the sort of screenshots we get from students). + +Create a secret snippet that contains your stack trace (copy/paste it from the NetBeans output pane), and include the URL in your message when you email us. diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Sharing Code Snippets.md.meta b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Sharing Code Snippets.md.meta new file mode 100644 index 0000000..6982f0e --- /dev/null +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Sharing Code Snippets.md.meta @@ -0,0 +1,6 @@ +created: 20200702091026430 +modified: 20200707005526287 +section: 4.1 +tags: lab02 +title: /Labs/02/Sharing Code Snippets +type: text/x-markdown \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Topic Branches.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Topic Branches.tid index b5f3c84..50337ac 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Topic Branches.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_Topic Branches.tid @@ -5,37 +5,53 @@ title: /Labs/02/Topic Branches type: text/x-markdown -The 'master' branch is the primary branch in a Git repository. It is where the primary version of the code should reside. +The 'master' branch is the primary/default branch in a Git repository. It is where the primary version of the code usually resides. When working in a team it is important that you keep the master branch 'clean' --- that means that there should never be incomplete or broken code in the master branch. There are two good reasons for this: -* If you are working on a feature, but don't have it working yet, and you push your broken code to the master branch of a shared repository then you will effectively break all versions of the project for all of your team mates. They will probably not be happy about that. +* If you are working on a feature, but don't have it working yet, and you push your broken code to the master branch of a shared repository then you will effectively break all versions of the project for all of your team mates. Your team mates are unlikely to be happy with you for doing this. -* In order to avoid merge conflicts your should be regularly pulling from the shared repository so that you are working on the most recent version of the code. If you are doing all of your work in the master branch then you will need to merge your code with the changes coming from other developers, and you will likely need to regularly deal with merge conflicts (which is what you were trying to avoid by pulling in the first place). +* In order to avoid merge conflicts you should be regularly pulling from the shared repository so that you are always working on the most recent version of the code. If you are doing all of your work in the master branch then you will need to merge your code with the changes coming from other developers, and you will likely need to regularly deal with merge conflicts (which is what you were trying to avoid by regularly pulling in the first place). -To avoid these problems we can use 'topic' branches (sometimes also called 'feature' branches). A topic branch is a branch that you create to to work on an issue. You create and switch to the branch and work on the issue, and don't merge the branch back into master until the issue is resolved and tested. Since you are working on a branch that is not master then you are isolated from other developers. +To avoid these problems we can use 'topic' branches (sometimes also called 'feature' branches). A topic branch is a branch that you create to work on an issue. You create and switch to the branch and work on the issue, and don't merge the branch back into master until the issue is resolved and tested. Since you are working on a branch that is not master then you are isolated from other developers. Let's create a simple menu form that allows the user to access the main features of the system: -1. First we should add an issue to GitBucket. We are adding a form that allows the user to access the main features of the system, so create an issue that that describes this feature. +1. First we should add an issue to GitBucket. We are adding a menu that allows the user to access the main features of the system, so create an issue that that describes this feature. -2. To ensure that we are up to date we should pull from the remote repository. We are pretending that we are working in a team here. Before starting any new feature you should ensure that you have the latest code. < Git > Remote > Pull from Upstream">>. +2. Before continuing, we should ensure that our repository is fully synced with the remote repository (we are pretending that we are working with a shared remote repository where other team members are regularly pushing their own changes): -2. Now we need to create a topic branch for this feature. < Git > Branch/Tag > Create Branch">>. + * Commit the entire project. < Git > Commit">>. - Enter 'topic/main_menu' as the branch name. + The only way you can lose work in Git is by not committing it. We are committing here in case we have to perform a merge when syncing with the remote server --- if all of our work is committed then it will be included in the merge. + + * Pull from upstream. < Git > Remote > Pull from Upstream">>. + + This ensures that we have the latest version of the code in our local repository. If you are working with an out-of-date version of the code then you may find that when you try to push, you get a merge conflict because another team member has also worked on the same code as you. It is good practice to pull before you do anything --- it dramatically reduces the amount of merge problems you will encounter. + + * Push to upstream. < Git > Remote > Push to Upstream">>. + + This ensures that the shared repository includes any changes that you have made. The longer you wait before pushing then the larger the window is for another team member to push changes to the same code. If this happens then you will be forced to pull (Git will insist that you pull if it detects that the remote branch is ahead of your local branch), and you will have to deal with a merge conflict. + + If you are regularly having to deal with merge conflicts then it is YOU that is causing it --- Git problems are largely self-inflicted. Commit, pull, and push (in that order) regularly to ensure that your local repository is synced with the remote server --- doing this regularly will avoid most of the problems. You will always want to do this before starting on a new issue. + +3. Now we need to create a topic branch for this issue. < Git > Branch/Tag > Create Branch">>. + + Enter `topic/main_menu` as the branch name. Make sure the <> checkbox is ticked. -3. Open the repository browser pane. You should now be able to see that your repository is using the 'topic/main_menu' branch. +4. Look at the branches using the repository browser pane (< Local">>). You should now be able to see that your repository is using the `topic/main_menu` branch since it will be bold --- the bold branch is the current branch. -3. In the repository browser, expand < Local">> to see your branches. + You should also be able to see the current branch beside the root of your project in the projects pane. If you don't see this then you should enable this using the < Show Versioning Labels">>. -4. Create a Java Swing Dialog using < New File > Swing GUI Forms > JFrame Form">>. + Any commits that are made at this point will go into the topic branch rather than `master`. When working with branches you need to keep an eye on the current branch. It can be easy to add commits to the wrong branch if you aren't paying sufficient attention. + +5. Create a Java Swing Dialog using < New File > Swing GUI Forms > JFrame Form">>. Name the file `MainMenu` and put it in a package named `gui`. -5. The NetBeans GUI editor will open up. Play around with it. The lo-fi mockup of the menu looks like the following: +6. The NetBeans GUI editor will open up. Play around with it. The lo-fi mockup for the menu looks like the following: {{/Labs/02/images/Main Menu Mockup}} @@ -43,32 +59,52 @@ We will give you more information on how to work with the GUI editor in next week's lab. -7. Commit your `gui` package. +7. Commit your `gui` package. Remember to reference the issue. -8. You can push topic branches if you want to, but generally you do not want to share them with the rest of the team --- they are temporary branches that can be deleted once they have been merged back into master. You might want to push a topic branch if you think it is that it is going to take you a while to complete the issue, or you need to use more that one computer (which is common if you need to test the code on a different environment). To push a branch you use <>> rather that <>. You will be given the opportunity to choose which branches you want to push. +9. Before merging the topic branch, we need to sync it with the remote master so that it includes any changes made by team members. First we need to update the local master: -8. We need to regularly sync our repository with the remote master so that we get changes made by other developers. You never want to be working on a code base that is out of date --- that is a recipe for problems when you try to push your code. To synchronise (pull) master, we first need to switch back to the master branch. In the repository browser, < Checkout Revision > Checkout">>. + * Switch to the master branch using the the repository browser. Right click the local master branch, and then select < Checkout">>. -9. Pull from upstream. + * Pull from upstream. -9. Checkout the topic branch again. < Checkout Revision > Checkout">>. + Now we have the latest code in the local master. -9. Merge your master branch onto your topic branch. This ensures that your topic branch is up to date. It also ensures that if there are going to be any merge conflicts caused by merging with the rest of the team's work then it will happen in your topic branch and not in master --- this is important to help keep your master clean. +10. Switch back to the topic branch again. Right click < Checkout Revision > Checkout">>. - < Merge Revision">>. The default settings are fine, so click <>. +11. Merge the local master branch. Right click < Merge Revision">>. The default settings are fine, so click <>. - Your topic branch is now fully up to date and includes all changes that are in master, and should be able to be merged back into master without any problems. + Note that merge operations are performed in the current branch. You need to first checkout the branch (which we did in the previous step) that you want to perform the merge in. -1. Switch back to master by checking it out. < Checkout Revision > Checkout">>. + Your topic branch is now fully up to date and includes all changes that are in both the remote and local master, and should be able to be merged back into master without any problems since everything is based on the most up-to-date code. - Uh oh, your menu just vanished from your project. That is expected --- that work exists only in the topic branch. We are about to fix that by merging the topic branch back into master. +12. You should test your system to ensure that nothing was broken by merging the remote changes. There is not much for you to do here other than checking that your menu still looks OK. If you had automated tests (we will start adding tests in next week's lab) then you would run those tests to check the system. -1. Merge the topic branch back to master. < Merge Revision > Merge">>. +12. Switch back to master by checking it out. - Your menu should be back now, since we have merged the topic branch back into master. + Uh oh, your menu just vanished from your project. That is expected --- that work currently only exists in the topic branch since it hasn't yet been merged into the local master yet. -1. Push to GitBucket. +13. Merge the topic branch. Right click < Merge Revision > Merge">>. -It is up to you whether you want to use topic branches in INFO202. There is some benefit --- it allows you to work on multiple issues at the same time. You can also use topic branches to work on experimental code that you are not sure will work --- if the experiment doesn't pan out then you delete the topic branch without ever merging it back into master. You do need to be careful though. If you aren't regularly merging your branches (first, master into your topic branches, and then your topic branches into master) then you can make a mess. + Your menu should be back, since we have merged the topic branch back into master. + +14. Push to upstream to share your completed work with the rest of the team. + +15. Check GitBucket. You should be able to see your `MainMenu` class. + +16. The following is more of an FYI. You don't have to do anything here for this lab. + + Topic branches are temporary branches that can be deleted once they have been merged back into master, and generally don't need to be pushed unless you have a good reason to do so. You might want to push a topic branch to a remote server if you want another team member to take a look at your work, or you need to use more than one computer (which is common if you need to test the code on a different environment, or you are working from multiple locations). + + To push a branch you use <> rather than <>. You will be asked to choose which branches you want to push, and you can select your topic branch. + + You should delete the remote topic branch once you are finished with it, otherwise you could end up with hundreds of useless branches on your git server. You can delete remote topic branches in the repository browser by deleting them from the < Remote">> and selecting <>. You have only deleted the local version at this point --- you still need to push the deletion --- use <> rather than <>. You will need to click the <> button before NetBeans will let you select the deleted branch. + +17. Delete the local topic branch by right clicking it in < Local">> and selecting <>. If a dialog pops up telling you that the branch has not been properly merged then may have messed up the merge. Go back and work through steps 12 and 13 again. + +18. Close the issue since we have completed the associated task. You can do this from GitBucket. Open the issue, and click the little up arrow to the right of the <> button. Select <>, and then click the <> button. + +It is up to you whether you want to use topic branches in INFO202. There is some benefit to using topic branches even in a single-developer scenario --- it allows you to work on multiple issues at the same time (not recommended, but occasionally necessary if you need to fix a bug in another part of the system while still working on an incomplete feature). You can also use topic branches to work on experimental code that you are not sure will work --- if the experiment doesn't pan out then you delete the topic branch without ever merging it into master. + +You do need to be careful though. If you aren't regularly merging your branches (first, master into your topic branches, and then your completed topic branches into master) then you can make a mess. If you aren't confident with using Git then you should stick to doing all of your work in the master branch. \ No newline at end of file diff --git a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_images_Project Domain Model.tid b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_images_Project Domain Model.tid index f76cbd0..9089529 100644 --- a/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_images_Project Domain Model.tid +++ b/tiddlywiki/tiddlers/content/labs/lab02/_Labs_02_images_Project Domain Model.tid @@ -12,9 +12,10 @@ RankSep 80 LineType ortho Style strictuml - RoundCorner 6 + RoundCorner 5 AttributeIconSize 0 Class { + FontSize 13 AttributeIconSize 0 ArrowFontSize 10 Stereotype { @@ -27,28 +28,28 @@ } class Customer { - - customer ID : Integer <> <> + - customerId : Integer <> <> - username : String <> - - first name : String + - firstName : String - surname : String - password : String - - email address : String - - shipping address : String + - emailAddress : String + - shippingAddress : String -- } class Product { - - product ID : String <> + - productId : String <> - name : String - description : String - category : String - - list price : BigDecimal - - quantity in stock : BigDecimal + - listPrice : BigDecimal + - quantityInStock : BigDecimal -- } class Sale { - - sale ID : Integer <> <> + - saleId : Integer <> <> - date : LocalDateTime - status : String -- @@ -57,8 +58,8 @@ } class SaleItem { - - quantity purchased : BigDecimal - - sale price : BigDecimal + - quantityPurchased : BigDecimal + - salePrice : BigDecimal -- + getItemTotal() : BigDecimal } @@ -66,6 +67,5 @@ Sale -up-> "**1**\r-customer " Customer Sale -right-> "-items\r**0..*** " SaleItem SaleItem -up-> "**1**\r-product " Product - @enduml ]]]