-
Notifications
You must be signed in to change notification settings - Fork 0
Development Guidelines
This page contains a set of guidelines and conventions for the entire development process. There may be additional points along the way.
Contents:
We conduct weekly sprint meetings with our TA. In every meeting, we answer some questions: What have we done last week? What is our plan for the next week? What are the blockers? We ask TA questions at the end of each meeting.
Based on specific situations, we might divide our team into smaller teams and conduct meetings for those teams. Usually, they are work sessions and do not have a meeting minute.
A normal development process will roughly follow these steps:
- Obtain your issue number from the project page
- From the
developbranch, checkout to the new branch with the naming convention ofissues/<your issue number>. For example, if your issue number is 16 then you need to check out a new branch with the nameissues/16fromdevelopusinggit checkout -b issues/16 - Implement your solution, make sure to commit often, with descriptive commit message. Preferably, address your commit message in the format "Added / Modified / Fixed <functionality, bugs> to <file name(s)>" and elaborate more in the description of the message
- Make sure to continuously update your local
developbranch usinggit pull, and merge that branch with the branch you are working on to ensure receiving the newest version of the code - Once you are happy with your implementation, push your branch to a new branch on GitHub, using
git push origin <your branch name> - Create a pull request to the remote
developwith the name of the PR matched the issue title - Give a brief description for the PR (see a template below for PR description)
- Tag someone to review your code
- The reviewer will have to pull the branch, run the code, test it, then request changes or approved by comment "LGTM!" to the PR
- Merge and close your PR, notify the team about the merge
- Move on to the next issue
In this PR, I have:
- Done A
- Finished B
- Fixed C
Note:
- A only covered D
- B is only implemented using technology E
To ensure code quality and avoid mass confusion, we have decided to adopt some code conventions. These are to be modified if the situation requires, but until then, all of us adhere to the following:
1. Order of Class/Interface Declarations:
- Class/Interface documentation comment (such as Javadoc)
- Class/Interface statement
- Class/Interface implementation comment (optional - if necessary)
- Class (static) variables. Order: public, protected, no access modifier, private.
- Instance variables. Order: public, protected, no access modifier, private.
- Constructors
- Methods (grouped by functionality rather than scope or accessibility)
2. Avoid the use of deprecated features.
3. Avoid lines longer than 80 characters.
Some of these conventions are taken from those introduced in CMPUT 301 document: Code Conventions (Schoepp).pdf
While developing this app, we are required to write javadoc for every java file, including Activities, Fragments, and Tests. Some of the tags we will be skipping are @see (too complicated), @link (too messy), @version and @since (we only have 1 version), and @deprecated (also because we only have 1 version). Below is a brief guide. If you don't know how to write descriptions properly, hoover your mouse over any not-user-defined class or method in your Java file and see how they wrote.
When documenting classes, we shall only be using @author.
// for documenting classes
/**
* "Class description"
* @author "name of the author - use real name"
*/
public class Example {
...
}When documenting methods, we shall be using @param, @return, and @throws.
/**
* "Method description"
* @param x1 "description for x1"
* @param x2 "description for x2"
* @return i "description of the return"
* @throws "what exception does it throw, in what case?"
*/
public int Example(int x1, String x2) throws SomeException {
...
return i;
}Github is the control center of our project, and we would like everyone, especially developers, to understand it in and out. Remember that status, type, label, and milestones are all used on issues and that we reference issues when those are brought up.
Currently, we have 5 kinds of status. The name of each is self-explanatory:
- Todo
- In progress
- Waiting for Review
- Under Review
- Done
We have different kinds of issues:
- Documentation: For any issue that is not code related.
- Bug: Reporting a bug.
- Urgent: For unexpected problems that need to be fixed as soon as possible.
- Enhancement: For newly proposed features that are not required by the description.
- Refine: For issues related to refining already working code for better code quality.
- Abandoned: We shall no longer be working on this issue.
Keep in mind that just being close to the deadline does not make an issue "Urgent". The issue has to be unexpected (might be a bug or a requirement done wrong), close to the deadline, and has significant impact on the project
We have different kinds of labels for each issue:
- half-way checkpoint: For user stories that we have to present at half-way checkpoint (part 3)
- help needed: When you took too much time on an issue and you are not coming up with a solution, you can post an issue with this tag (an with description as detailed as possible) to ask for help.
- Risk Level: Low/Medium/High: Used for risk analysis. The more risk the feature has (i.e. if this feature breaks, many others will), the higher the risk level.
- Size: 1/3/5/8: Size of user story, which estimates the time needed to finish the story by assigning story points. Each point estimates 2 hours of work.
We currently have 3 milestones:
- For documentation:
- Project Part 2: Preparation
- Project Part 3: Half-way Checkpoint
- Project Part 4: Final Checkpoint