Course Related Materials - rsanchez-wsu/jfiles GitHub Wiki
This project is being developed by undergraduate students at Wright State University as coursework. The program is being worked on by a new set of students from semester-to-semester. Students in the class must divide themselves into separate teams and pick up the work left over from the previous semester. As such, communication is key for development. The following topics discuss the different aspects of project development in regards to writeups and communication.
Contents
Issues
GitHub will be used as the main source for hosting and collaborating on files. This also allows us to use the feature called "Issues". This is a built-in ticketing system that allows us to keep track of tasks and bugs.
For course participation, almost all work should be work done towards an issue on GitHub. This allows work to be tracked in two ways: via commits made to the project, and by any deliverable or end-state achieved towards an open issue.
Note: Issues are usually tucked into a Milestone container. The Milestone allows for associated tasks to be collected together to define a certain phase of a project (whether it's based on time or goals). You can read more about Milestones as you scroll through this page.
To create a new issue, click on the Issues tab at the top of the web page for this GitHub project.
The new issue will require a short descriptive title. It's a good idea to assign the issue to someone - all contributors should be searchable when clicking on the Assignees label. However, the teacher suggest restricting the assignees to two people per issue. This helps from assigning too many resources to one particular bug and keeps people from stepping on each others' toes.
Clicking on the Label will allow you to tag the issue or create a new label, and clicking on the Milestone will allow you to assign the issue to a team. If you have not created a new milestone for the upcoming week, you can come back to this issue and tag it later.
The main comment window should describe any issues in a detailed and professional manner. The content should describe the objective, state the desired end state/deliverable in an identifiable or measurable manner. The end state should be achievable by one or two people within a given timeframe (usually 1 week). If the issue cannot be completed in one week, then the issue can probably be divided into smaller components, which warrant issues (tickets) of their own. (Contents of this portion are paraphrased from Roberto Sanchez' lecture slides.)
The comment window allows for tagging of collaborators by appending the @ symbol before their username: For example, @burks20 will tag the user into the issue. Mentioning an issue will automatically cross-link the issues: For example, typing issue 263 will automatically create a link to the associated issue if it exists.
Examples of well-written issues:
- https://github.com/rsanchez-wsu/jfiles/issues/141
- https://github.com/rsanchez-wsu/jfiles/issues/146
- https://github.com/rsanchez-wsu/jfiles/issues/147
- https://github.com/rsanchez-wsu/jfiles/issues/149
Milestones
As mentioned above, issues are usually tucked away into Milestone containers because they allow for associated tasks to be collected together to define a certain phase of a project.
Milestones are expected to be thorough, professional, and detailed. You are to ensure that your team's overall objective for the milestone is clearly stated. This means that if the milestone is a carry-over from the previous week, that needs to be clearly stated as well. The milestone writeups and the constituent issues should be detailed and clear enough that it should enable a different team to pick up your team's work and complete the milestone without questions. Each milestone writeup is submitted once per group with everyone receiving the same grade.
To create a new milestone, first click on the Issues tab at the top of the web page for this GitHub project.
Next, click on the Milestones button near the top, next to the Labels button.
Following the "New milestone" link as shown below will open up the page to create your milestone.
As shown on the right side of the image above, there is an option to include a due date for your milestone. Including this date is recommended, as it will be helpful in keeping each of your group members aware of the deadlines. The title window should typically just address the team number and the milestone number. For example, "Team 1 - Milestone 1". The description window should be thorough, professional, and detailed in describing your team's overall objective for the milestone. The content should describe the objective and state the desired end state/deliverable for that week.
For the purposes of this course, the links for each milestone are to be pasted in a text document and submitted to the appropriate dropbox on pilot.wright.edu.
Example of a well-written milestone:
Example of a poorly-written milestone:
Commit Messages
When making changes to the code, thorough, professional, and detailed messaged must be given as an explanation of the purpose of the commit. Give a short (less than about 60 characters) summary, followed by a blank line, and then followed by a more detailed explanation of the change. Mention specific issues and commits as appropriate; for example, if a previous commit relates to your current one, mention that in the message. Make sure to provide as much information about the commit as possible: The more information, the better. If the commit is really is small, a less detailed commit message may be acceptable.
Example of a good commit message:
Finished Preliminary JavaDoc Information
This commit finishes the Java documentation for the JFileManager class for Milestone 1. It also adds comments either referencing conversations between Team 5 members or bringing up issues that were just realized as I went through and thought through how class needs to work.
Note that this commit only finishes the skeleton structure for the class, few methods have actually been worked on.
We will add to the documentation as other teams discuss what they need from us and as we implement method they have made.
fixes #12
Participation Writeups
Participation writeups are expected to be thorough, professional, and detailed. The point of these writeups are to focus on each student's individual effort towards their team's Milestone. Each participation writeup should mention specific commits which was pushed, specific issues which was worked on, and/or specific wiki pages which was edited or created. If a Wiki page was edited, view the page history, compare the proper revisions, and then use that URL generated when viewing revision comparison. A step-by-step process of how to accomplish this is shown below:
First, view the page history by clicking on the number of revisions displayed on the Wiki page that was edited.
Next, click the checkboxes of the revisions you would like to compare to show the changes you made. Then click Compare Revisions.
Finally, copy the URL of the resulting webpage to your writeup. If you created the Wiki page yourself, then just including the link to the wiki is sufficient. If you had any work related to the project done that is not associated with a project artifact, be especially detailed about that work.
For the purposes of this course, the participation writeup should be pasted in a text document and submitted to the appropriate dropbox on pilot.wright.edu.
Example of a good participation writeup:
This week, I was once again leading the team discussion on our next Milestone. I suggested several ideas that were turned into issues for milestone 8. I also coordinated with team 4 in gather requirements for the LIST command and specifics of how to use the XmlHandler class. From this collaboration, we created 1 issue (#191) to address a concern regarding sending a directory vs. sending its content. I also made several commits (b37ca89, 33e8966, and 2028b90) to improve code quality in anticipation of pushing our code to the master branch. I also have committed work (718d321) to improve the FileStruct class. The object type is now an attribute in the XML and defined by an inner enum class. Also in this commit, I changed the constructor parameter of the XmlHandler class to a string so that it would fully accept paths with trailing slashes. Lastly, I committed work (3cf0011) to continue work on XStream field and attribute aliases.
Example of a bad participation writeup:
Most of the week was spent on researching B trees so that we can properly index the file system, and make search faster
the other part of the week was organizing the group and trying to get brett to translate sample command so that group can see how all the classes work together
Slack
This project and its related course uses asynchronous communication methods for contribution and participation. If you are a student taking the course at Wright State University, please head to the course syllabus on pilot.wright.edu to find the appropriate link (URL) to join our Slack channels.
You will have to manually join some of the following channels:
- random
- general
- github
- team1
- team2
- team3
- (...etc)