Please follow these guidelines with respect to project development in this class.
This section provides guidelines for using GitHub’s mechanisms for project hosting to document and present your project in a manner suited to satisfying the Three Prime Directives.
A new developer should be able to build the system without obtaining additional files from you.
Follow the practices demonstrated during development of the Digits application. Do development of new functionality in branches, then merge into master when completed.
Create a top-level directory called “doc”, and a directory within it called “images”. Store screenshots and any other images for your documentation in this directory.
The home page for your application should:
A summary of the system and what it does. Include at least one helpful screen image.
What makes it special and different from other related applications.
Links to the User Guide, Developer Guide, and Contact page.
A link to the deployed application.
Your home page should be published using GitHub Pages. The easiest way to do this is to write your home page content in your top-level README.md file, then go to Settings > GitHub pages and use the Automatic Page Generator to use the contents of README.md as your home page.
Note: each time you change the README.md file contents, you must “republish” the GitHub page version. It does not automatically update with the latest version of the README.md.
The User Guide should explain to a new user how to use the system. If hosted on Heroku, you can just point the user to the home page URL on Heroku and then guide them through the pages and functionality.
The Developer Guide should explain to a new developer how to install any prerequisite tools and libraries, download the sources, and then build, run, and test the system. It should also discuss the design of the system (as well as any associated documentation such as the JavaDocs).
If you are deploying the system to Heroku, the Developer Guide should document how to do this.
The Contact Us page should indicate how to get in touch with developers, and whether there are any StackOverflow tags, Google discussion groups, or other mailing lists for this project.
When you have obtained a stable release of your system (such as when delivering a milestone) use the GitHub release manager to indicate the sources associated with the release.
This section presents guidelines to be followed to support effective group work in this class.
For this approach to project management to be effective, your team must commit to meeting together every 2-3 days to review progress and update the upcoming set of tasks to complete.
For multiple people to work together effectively, you must decompose the system into small tasks. As a guideline, each task should take no longer than three days to accomplish. If a task appears to take longer than that, then decompose it into subtasks.
You do not have to figure out the entire project’s tasks on Day 1. At any time, you only need to have the next 3-4 days of tasks precisely specified, since you will meet again within 3 days to revise the task list.
Specify each task as a GitHub issue, and make one team member the owner. While multiple people might participate in completing a task, you should always specify a single person as having ultimate responsibility for completing it.
To prioritize which tasks to work on, create a sequence of Milestones in the GitHub Issue system. Each Milestone has a due date and every Issue is associated with a single Milestone.
To ensure that everyone has something to do, there should always be two issues associated with each person. That way, if they finish what they are working on before the next meeting, they have another task they can switch to immediately.
When a commit involves work associated with an Issue, document it in the commit message using #<issue number>. You can put multiple Issue numbers in a commit message if appropriate.
Sometimes you will fix something small and there’s no associated Issue. That’s inevitable, but please make sure that happens rarely; say, less than 20% of the time.
We will be using HuBoard to help manage GitHub Issues. I have obtained a free educational license for HuBoard so you won’t have to pay anything to use it for this class.
Before using HuBoard for the first time, be sure you have set up your TextBookMania repo.
Then, login to HuBoard and give it access to your public repositories. You should find that your TextBookMania repo is listed.
HuBoard defines five labels for tracking progress, and displays them as columns in the HuBoard interface:
Backlog. The backlog column represents issues that are not currently scheduled for work. If you think of something that will eventually require work, but don’t want it worked on at the moment, put it in the Backlog column.
Ready. The ready column represents issues that are ready to be addressed by the team. At all times during development, each member of the team should have an issue in the ready column.
Working. When a team member takes on a task, the associated issue should be moved from the ready column to the working column. All members of the team should always have an issue that they are working on. It is OK for a team member to be working on more than one issue at a time.
In most cases, work should be done in a branch off the master branch.
Review. When a task has been completed, the team member can move it to the review column, which indicates that they would like other team members to look at what they’ve finished.
Done. When a task has been completed (and the associated branch has been successfully merged back into master), then the associated issue can be moved into the done column.