iP:
A-BetterGuitP:
A-BetterGuiA-BetterGui: Better GUI optionalImprove the GUI to make it more polished. Some examples:
You can take inspiration from these past projects. If you adopt any ideas from them, don't forget to give credit to the original author.
Admin Module Policies → Policy on Reuse
Reuse is encouraged. However, note that reuse has its own costs (such as the learning curve, additional complexity, usage restrictions, and unknown bugs). Furthermore, you will not be given credit for work done by others. Rather, you will be given credit for reusing work done by others.
Given below are how to give credit for things you reuse from elsewhere. These requirements are specific to this module i.e., not applicable outside the module (outside the module you should follow the rules specified by your employer and the license of the reused work)
If you used a third party library:
README file (under the Acknowledgements section)If you reused code snippets found on the Internet e.g. from StackOverflow answers or
referred code in another software or
referred project code by current/past student:
//Solution below adapted from https://stackoverflow.com/a/16252290
{Your implmentation of the reused solution here ...}
@@author tags with the -reused suffix)//@@author {yourGithubUsername}-reused
//{Info about the source...}
{Reused code (possibly with minor modifications) here ...}
//@@author
persons = getList()
//@@author johndoe-reused
//Reused from https://stackoverflow.com/a/34646172 with minor modifications
Collections.sort(persons, new Comparator<CustomData>() {
@Override
public int compare(CustomData lhs, CustomData rhs) {
return lhs.customInt > rhs.customInt ? -1 : 0;
}
});
//@@author
return persons;
Giving credit to AB3 code: If your project started with the AB3 code and your new code follows a design similar to AB3, that doesn't mean you need to credit AB3 -- this is because new code is expected to follow existing code where possible, in the interest of consistency. However, don't take credit for existing AB3 code (i.e., ensure such code doesn't appear under your name in the tP code dashboard) unless you have modified them substantially.
@@author tags indicate authorshipMark your code with a //@@author {yourGithubUsername}. Note the double @.
The //@@author tag should indicates the beginning of the code you wrote. The code up to the next //@@author tag or the end of the file (whichever comes first) will be considered as was written by that author.
Here is a sample code file:
//@@author johndoe
method 1 ...
method 2 ...
//@@author sarahkhoo
method 3 ...
//@@author johndoe
method 4 ...
If you don't know who wrote the code segment below yours, you may put an empty //@@author (i.e. no GitHub username) to indicate the end of the code segment you wrote. The author of code below yours can add the GitHub username to the empty tag later.
Here is a sample code with an empty author tag:
method 0 ...
//@@author johndoe
method 1 ...
method 2 ...
//@@author
method 3 ...
method 4 ...
The author tag syntax varies based on file type e.g. for java, css, fxml. Use the corresponding comment syntax for non-Java files.
Here is an example code from an xml/fxml file.
<!-- @@author sereneWong -->
<textbox>
<label>...</label>
<input>...</input>
</textbox>
...
Do not put the //@@author inside java header comments.
👎
/**
* Returns true if ...
* @@author johndoe
*/
👍
//@@author johndoe
/**
* Returns true if ...
*/
Annotate both functional and test code There is no need to annotate documentation files.
Annotate only significant size code blocks that can be reviewed on its own e.g., a class, a sequence of methods, a method.
Claiming credit for code blocks smaller than a method is discouraged but allowed. If you do, do it sparingly and only claim meaningful blocks of code such as a block of statements, a loop, or an if-else statement.
Do not try to boost the quantity of your contribution using unethical means such as duplicating the same code in multiple places. In particular, do not copy-paste test cases to create redundant tests. Even repetitive code blocks within test methods should be extracted out as utility methods to reduce code duplication. Individual members are responsible for making sure code attributed to them are correct. If you notice a team member claiming credit for code that he/she did not write or use other questionable tactics, you can email us (after the final submission) to let us know.
If you wrote a significant amount of code that was not used in the final product,
{project root}/unused//@@author {yourGithubUsername}-unused to mark unused code in those files (note the suffix unused)
e.g.//@@author johndoe-unused
method 1 ...
method 2 ...
Please put a comment in the code to explain why it was not used.
If you reused code from elsewhere, mark such code as //@@author {yourGithubUsername}-reused (note the suffix reused)
e.g.
//@@author johndoe-reused
method 1 ...
method 2 ...
You can use empty @@author tags to mark code as not yours when RepoSense attribute the code to you incorrectly.
Code generated by the IDE/framework, should not be annotated as your own.
Code you modified in minor ways e.g. adding a parameter. These should not be claimed as yours but you can mention these additional contributions in the Project Portfolio page if you want to claim credit for them.
At the end of the project each student is required to submit a Project Portfolio Page.
Team-tasks are the tasks that someone in the team has to do.
Examples of team-tasks
Here is a non-exhaustive list of team-tasks:
Keep in mind that evaluators will use the PPP to estimate your project effort. We recommend that you mention things that will earn you a fair score e.g., explain how deep the enhancement is, why it is complete, how hard it was to implement etc..
docs/team/githbub_username_in_lower_case.md e.g., docs/team/goodcoder123.mdTo convert the UG/DG/PPP into PDF format, go to the generated page in your project's github.io site and use this technique to save as a pdf file. Using other techniques can result in poor quality resolution (will be considered a bug) and unnecessarily large files.
Ensure hyperlinks in the pdf files work. Your UG/DG/PPP will be evaluated using PDF files during the PE. Broken/non-working hyperlinks in the PDF files will be considered as bugs and will count against your project score. Again, use the conversion technique given above to ensure links in the PDF files work.
The icon indicates team submissions. Only one person need to submit on behalf of the team but we recommend that others help verify the submission is in order i.e., the responsibility for (and any penalty for problems in) team submissions are best shared by the whole team rather than burden one person with it.
The icon indicates individual submissions.
| Content | Recommended | Hard Limit |
|---|---|---|
| Overview + Summary of contributions | 0.5-1 | 2 |
| [Optional] Contributions to the User Guide | 1 | |
| [Optional] Contributions to the Developer Guide | 3 |
docs folder.
docs folder and named Ui.png exactly (even if the file format is not png, name it png)Admin Team Project (tP) → Tips for Product Screenshots
Some common sense tips for a good product screenshot
Ui.png represents your product in its full glory.
Examples
Reason: Distracting annotations.
Reason: Not enough data. Should have used real profile pictures instead of placeholder images.
Reason: screenshot not cropped cleanly (contains extra background details)
A-UserGuide: User Guide Add a User Guide to the project. Here is one simple way to do it.
docs\README.md. See this guide to GitHub flavored Markdown (GFMD).docs folder (you can select a theme too).http://{your username}.github.io/{repo name}/ to view the user guide of your product. Note: it could take 5-10 minutes for GitHub to update the page.Ui.png correctly and set up the product website correctly, you should be able to see your screenshot in the iP Showcase page (a link to the iP Showcase page is also available in the top navigation menu → Links).
Soft deadline: midnight before the tutorial
Create a new jar file
Do the following smoke tests to ensure the jar file works (reason: a similar flow will be used when grading your iP).
Create a new release on GitHub (e.g., v0.2) and upload the JAR file.
indicates an individual task (i.e., each team member has to do the task, graded individually) while indicates a team task (some or all members may do the work; graded for the whole team).
tP tasks progress is graded. Completing individual and team tasks are considered for grading the project management component of your project grade.
Admin tP → Grading → Project Management
5A. Process:
Evaluates: How well you did in project management related aspects of the project, as an individual and as a team
Based on: tutor/bot observations of project milestones and GitHub data
Grading criteria:
5B. Team-tasks:
Evaluates: How much you contributed to team-tasks
Admin tP → Expectations: Examples of team-tasks
Here is a non-exhaustive list of team-tasks:
Based on: peer evaluations, tutor observations
Grading criteria: Do these to earn full marks.
Most aspects of project progress are tracked using automated scripts. Please follow our instructions closely or else the script will not be able to detect your progress. We prefer not to waste admin resources processing requests for partial credit for work that did not follow the instructions precisely, unless the progress was not detected due to a bug in the script.
Milestone requirements are cumulative. The recommended progress for the mid-milestone is an implicit requirement for the actual milestone unless a milestone requirement overrides a mid-milestone requirement e.g., mid-milestone requires a document to be in a temp format while the actual milestone requires it to be in the proper format. Similarly, a requirement for milestone n is also an implicit requirement for milestone n+1 unless n+1 overrides the n requirement. This means if you miss some requirement at milestone n, you should try to achieve it before milestone n+1 or else it could be noted again as a 'missed requirement' at milestone n+1.
Requirements → Specifying Requirements → Feature Lists →
Feature list: A list of features of a product grouped according to some criteria such as aspect, priority, order of delivery, etc.
A sample feature list from a simple Minesweeper game (only a brief description has been provided to save space):
{team-id}.pdf e.g., CS2103-T09-2.pdf, and upload to LumiNUS.Recommended: Divide i.e., work related to the User Guide and the Developer Guidedocumentation work among team members equally; preferably based on enhancements/features each person would be adding e.g., If you are the person planing to add a feature X, you should be the person to describe the feature X in the User Guide and in the Developer Guide.
Reason: In the final project evaluation your documentation skills will be graded based on sections of the User/Developer Guide you have written.
Admin tP: Grading → Documentation
Evaluates: your contribution to project documents
Method: Evaluated in two steps.
Admin tP → PE → Grading Instructions for User Guide
Evaluate based on fit-for-purpose, from the perspective of a target user.
For reference, the AB3 UG is here.
Admin tP → PE → Grading Instructions for Developer Guide
Evaluate based on fit-for-purpose from the perspective of a new team member trying to understand the product's internal design by reading the DG.
For reference, the AB3 DG is here.
Admin Peer Evaluations → Questions used for Evaluating the Contribution to the UG
Admin Peer Evaluations → Questions used for Evaluating the Contribution to the DG
Uses the Equal Share +/- N% scale for the answer
These are considered UG bugs (if they hinder the reader):
Use of visuals
Use of examples:
Explanations:
Neatness/correctness:
These are considered DG bugs (if they hinder the reader):
Those given as possible UG bugs ...
These are considered UG bugs (if they hinder the reader):
Use of visuals
Use of examples:
Explanations:
Neatness/correctness:
Architecture:
UML diagrams:
Code snippets:
Problems in User Stories. Examples:
Problems in Use Cases. Examples:
Problems in NFRs. Examples:
Problems in Glossary. Examples:
Admin tP: Grading → Product Design
Evaluates: how well your features fit together to form a cohesive product (not how many features or how big the features are) and how well does it match the target user
Evaluated by:
Admin tP → PE → Grading Instructions for Product Design
Evaluate based on the User Guide and the actual product behavior.
| Criterion | Unable to judge | Low | Medium | High |
|---|---|---|---|---|
target user |
Not specified | Clearly specified and narrowed down appropriately | ||
value proposition |
Not specified | The value to target user is low. App is not worth using | Some small group of target users might find the app worth using | Most of the target users are likely to find the app worth using |
optimized for target user |
Not enough focus for CLI users | Mostly CLI-based, but cumbersome to use most of the time | Feels like a fast typist can be more productive with the app, compared to an equivalent GUI app without a CLI | |
feature-fit |
Many of the features don't fit with others | Most features fit together but a few may be possible misfits | All features fit together to for a cohesive whole |
In addition, feature flaws reported in the PE will be considered when grading this aspect.
These are considered feature flaws:
The feature does not solve the stated problem of the intended user i.e., the feature is 'incomplete'
Hard-to-test features
Features that don't fit well with the product
Features that are not optimized enough for fast-typists or target users
Admin Appendix E (extract): tP Organization Setup
Please follow the organization/repo name format precisely or else our grading scripts will not be able to detect your work.
(/) Only one team member:
After receiving your team ID, one team member should do the following steps:
AY2021S1-TEAM_ID. e.g. AY2021S1-CS2103T-W12-1, AY2021S1-CS2103-T09-2developers to your organization.Admin Appendix E (extract): tP Team Repo Setup
(/) Only one team member:
Fork the https://github.com/nus-cs2103-AY2021S1/tp repo to your team org.
Enable the issue tracker.
Enable GitHub Actions: Go to the Actions tab and enable workflows by clicking the button. That will enable the GitHub Actions that are already included in the repo you forked.
Set up the project website
Follow instructions in the Documentation guide page of AB3 developer guide. When set up correctly, your project website should be available via the URL https://ay2021s1-{team-id}.github.io/tp e.g., https://ay2021s1-cs2103-w13-1.github.io/tp.
Add members. Ensure your team members have the desired level of access to your team repo.
Recommended: Give admin access to 1-2 members and write access to others.
Create a team PR for us to track your project progress: i.e., create a PR from your team repo master branch to [nus-cs2103-AY2021S1/tp] master branch. PR name: [Team ID] Product Name e.g., [CS2103-T09-2] Contact List Pro. As you merge code to your team repo's master branch, this PR will auto-update to reflect how much your team's product has progressed.
Please fill in these details as specified because they are used by our grading scripts.
InsureListInsureList helps insurance agents manage detail of their clients. It is optimized for CLI users so that frequent tasks can be done faster by typing in commands.Admin Appendix E (extract): tP Individual Fork Setup
(, , , ...) Every team member:
tP repo (created above) i.e., go to the repo and click on the button to subscribe to activities of the repo.tP repo to your personal GitHub account.Do not alter these paths in your project as our grading scripts depend on them.
src/main/javasrc/test/javadocstutorial-removing-field and push to your fork.tutorial-adding-command, push to your fork, and create a PR from your fork to your team's repo.Admin Appendix E(extract): Workflow
Read our reuse policy (in Admin: Appendix B), in particular, how to give credit when you reuse code from the Internet or classmates:
Set Git user.name: We use various tools to analyze your code. For us to be able to identify your commits, we encourage you to set your Git user.name in all computers you use to a sensible string that uniquely identifies you. For example, you can set it to your GitHub username or your full name. If this user name is not set properly or if you use multiple usernames for Git, our grading scripts might miss some of your work.
After installing Git in a computer, you can set the Git username as follows:
git config --global user.name YOUR_GITHUB_USERNAME (omit the --global flag to limit the setting to the current repo only)git config --global user.name JohnDoeMore info about setting Git username is here.
Reuse is encouraged. However, note that reuse has its own costs (such as the learning curve, additional complexity, usage restrictions, and unknown bugs). Furthermore, you will not be given credit for work done by others. Rather, you will be given credit for reusing work done by others.
Given below are how to give credit for things you reuse from elsewhere. These requirements are specific to this module i.e., not applicable outside the module (outside the module you should follow the rules specified by your employer and the license of the reused work)
If you used a third party library:
README file (under the Acknowledgements section)If you reused code snippets found on the Internet e.g. from StackOverflow answers or
referred code in another software or
referred project code by current/past student:
//Solution below adapted from https://stackoverflow.com/a/16252290
{Your implmentation of the reused solution here ...}
@@author tags with the -reused suffix)//@@author {yourGithubUsername}-reused
//{Info about the source...}
{Reused code (possibly with minor modifications) here ...}
//@@author
persons = getList()
//@@author johndoe-reused
//Reused from https://stackoverflow.com/a/34646172 with minor modifications
Collections.sort(persons, new Comparator<CustomData>() {
@Override
public int compare(CustomData lhs, CustomData rhs) {
return lhs.customInt > rhs.customInt ? -1 : 0;
}
});
//@@author
return persons;
Giving credit to AB3 code: If your project started with the AB3 code and your new code follows a design similar to AB3, that doesn't mean you need to credit AB3 -- this is because new code is expected to follow existing code where possible, in the interest of consistency. However, don't take credit for existing AB3 code (i.e., ensure such code doesn't appear under your name in the tP code dashboard) unless you have modified them substantially.
@@author tags indicate authorshipMark your code with a //@@author {yourGithubUsername}. Note the double @.
The //@@author tag should indicates the beginning of the code you wrote. The code up to the next //@@author tag or the end of the file (whichever comes first) will be considered as was written by that author.
Here is a sample code file:
//@@author johndoe
method 1 ...
method 2 ...
//@@author sarahkhoo
method 3 ...
//@@author johndoe
method 4 ...
If you don't know who wrote the code segment below yours, you may put an empty //@@author (i.e. no GitHub username) to indicate the end of the code segment you wrote. The author of code below yours can add the GitHub username to the empty tag later.
Here is a sample code with an empty author tag:
method 0 ...
//@@author johndoe
method 1 ...
method 2 ...
//@@author
method 3 ...
method 4 ...
The author tag syntax varies based on file type e.g. for java, css, fxml. Use the corresponding comment syntax for non-Java files.
Here is an example code from an xml/fxml file.
<!-- @@author sereneWong -->
<textbox>
<label>...</label>
<input>...</input>
</textbox>
...
Do not put the //@@author inside java header comments.
👎
/**
* Returns true if ...
* @@author johndoe
*/
👍
//@@author johndoe
/**
* Returns true if ...
*/
Annotate both functional and test code There is no need to annotate documentation files.
Annotate only significant size code blocks that can be reviewed on its own e.g., a class, a sequence of methods, a method.
Claiming credit for code blocks smaller than a method is discouraged but allowed. If you do, do it sparingly and only claim meaningful blocks of code such as a block of statements, a loop, or an if-else statement.
Do not try to boost the quantity of your contribution using unethical means such as duplicating the same code in multiple places. In particular, do not copy-paste test cases to create redundant tests. Even repetitive code blocks within test methods should be extracted out as utility methods to reduce code duplication. Individual members are responsible for making sure code attributed to them are correct. If you notice a team member claiming credit for code that he/she did not write or use other questionable tactics, you can email us (after the final submission) to let us know.
If you wrote a significant amount of code that was not used in the final product,
{project root}/unused//@@author {yourGithubUsername}-unused to mark unused code in those files (note the suffix unused)
e.g.//@@author johndoe-unused
method 1 ...
method 2 ...
Please put a comment in the code to explain why it was not used.
If you reused code from elsewhere, mark such code as //@@author {yourGithubUsername}-reused (note the suffix reused)
e.g.
//@@author johndoe-reused
method 1 ...
method 2 ...
You can use empty @@author tags to mark code as not yours when RepoSense attribute the code to you incorrectly.
Code generated by the IDE/framework, should not be annotated as your own.
Code you modified in minor ways e.g. adding a parameter. These should not be claimed as yours but you can mention these additional contributions in the Project Portfolio page if you want to claim credit for them.
At the end of the project each student is required to submit a Project Portfolio Page.
Team-tasks are the tasks that someone in the team has to do.
Examples of team-tasks
Here is a non-exhaustive list of team-tasks:
Keep in mind that evaluators will use the PPP to estimate your project effort. We recommend that you mention things that will earn you a fair score e.g., explain how deep the enhancement is, why it is complete, how hard it was to implement etc..
docs/team/githbub_username_in_lower_case.md e.g., docs/team/goodcoder123.mdTo convert the UG/DG/PPP into PDF format, go to the generated page in your project's github.io site and use this technique to save as a pdf file. Using other techniques can result in poor quality resolution (will be considered a bug) and unnecessarily large files.
Ensure hyperlinks in the pdf files work. Your UG/DG/PPP will be evaluated using PDF files during the PE. Broken/non-working hyperlinks in the PDF files will be considered as bugs and will count against your project score. Again, use the conversion technique given above to ensure links in the PDF files work.
The icon indicates team submissions. Only one person need to submit on behalf of the team but we recommend that others help verify the submission is in order i.e., the responsibility for (and any penalty for problems in) team submissions are best shared by the whole team rather than burden one person with it.
The icon indicates individual submissions.
| Content | Recommended | Hard Limit |
|---|---|---|
| Overview + Summary of contributions | 0.5-1 | 2 |
| [Optional] Contributions to the User Guide | 1 | |
| [Optional] Contributions to the Developer Guide | 3 |
Follow the forking workflow in your project at least until (and including) v1.2 (you may tweak the workflow v1.3 onwards).
master branch: You can use GitHub's Protected Branches feature to protect your master branch against rogue PRs. We suggest the following:
Branches option on the navigation menu on the left.masterRequire status checks to pass before merging to ensure that a branch has to pass CI before it can be merged into the master branchRequire pull request reviews before merging option.LGTM is common abbreviation you can use in the review comments to mean Looks Good To Merge.master branch should take the product from a working version to a slightly better working version.
Details link in corresponding line to find out more about the failure. Once you figure out the cause of the failure, push the a fix to the PR.Fixes #123 trick to get the issue to close automatically when the PR is merged.master from the team repo and pushing it to your own fork.Project Management → Revision Control →
In the forking workflow, the 'official' version of the software is kept in a remote repo designated as the 'main repo'. All team members fork the main repo and create pull requests from their fork to the main repo.
To illustrate how the workflow goes, let’s assume Jean wants to fix a bug in the code. Here are the steps:
master branch -- if Jean does that, she will not be able to have more than one PR open at any time because any changes to the master branch will be reflected in all open PRs.Resources
Revision Control → Forking Workflow
Tools → Git and GitHub →
You can follow the steps in the simulation of a forking workflow given below to learn how to follow such a workflow.
This activity is best done as a team.
Step 1. One member: set up the team org and the team repo.
Create a GitHub organization for your team. The org name is up to you. We'll refer to this organization as team org from now on.
Add a team called developers to your team org.
Add team members to the developers team.
Fork se-edu/samplerepo-workflow-practice to your team org. We'll refer to this as the team repo.
Add the forked repo to the developers team. Give write access.
Step 2. Each team member: create PRs via own fork.
Fork that repo from your team org to your own GitHub account.
Create a branch named add-{your name}-info (e.g. add-johnTan-info) in the local repo.
Add a file yourName.md into the members directory (e.g., members/jonhTan.md) containing some info about you into that branch.
Push that branch to your fork.
Create a PR from that branch to the master branch of the team repo.
Step 3. For each PR: review, update, and merge.
[A team member (not the PR author)] Review the PR by adding comments (can be just dummy comments).
[PR author] Update the PR by pushing more commits to it, to simulate updating the PR based on review comments.
[Another team member] Approve and merge the PR using the GitHub interface.
[All members] Sync your local repo (and your fork) with upstream repo. In this case, your upstream repo is the repo in your team org.
Step 4. Create conflicting PRs.
[One member]: Update README: In the master branch, remove John Doe and Jane Doe from the README.md, commit, and push to the main repo.
[Each team member] Create a PR to add yourself under the Team Members section in the README.md. Use a new branch for the PR e.g., add-johnTan-name.
Step 5. Merge conflicting PRs one at a time. Before merging a PR, you’ll have to resolve conflicts.
[Optional] A member can inform the PR author (by posting a comment) that there is a conflict in the PR.
[PR author] Resolve the conflict locally:
master branch from the repo in your team org.master branch to your PR branch.[Another member or the PR author]: Merge the de-conflicted PR: When GitHub does not indicate a conflict anymore, you can go ahead and merge the PR.
After following the given workflow for at least i.e., until the end of v1.2one iteration, optionally, you may adjust the process rigor to suit your team's pace. Here are some examples:
Reduce automated tests: Automated tests have benefits, but they can be a pain to write/maintain.
It is OK to get rid of some of the troublesome tests and rely more on manual testing instead. The less automated tests you have, the higher the risk of regressions; but it may be an acceptable trade-off under the circumstances if tests are slowing you down too much.
There is no direct penalty for removing tests. Also note our expectation on test code.
Reduce automated checks: You can also reduce the rigor of checkstyle checks to expedite PR processing.
Switch to a lighter workflow: While forking workflow is the safest (and is recommended), it is also rather heavy. You may switch to a simpler workflow if the forking workflow if you wish. Refer the textbook to find more about alternative workflows: branching workflow, centralized workflow. Even if you do switch, we still recommend that you use PR reviews, at least for PRs affecting others' features.
If you are unsure if a certain adjustment is allowed, you can check with the teaching team first.
🤔 How much testings is enough? We expect you to decide. You learned different types of testing and what they try to achieve. Based on that, you should decide how much of each type is required. Similarly, you can decide to what extent you want to automate tests, depending on the benefits and the effort required.
There is no requirement for a minimum coverage level. Note that in a production environment you are often required to have at least 90% of the code covered by tests. In this project, it can be less. The weaker your tests are, the higher the risk of bugs, which will cost marks if not fixed before the final submission.