Milestone 1

Overall project summary

During this course you will work collaboratively in assigned teams of four to develop a Python software package. Your package could contain functions that: - are entirely new to the R or Python ecosystem or - improve upon pre-existing functions in either language or - re-implement existing code/functions that you wish to deepen your understanding of (e.g., in a past year one student decided to write a linear regression package from scratch).

At the end of this project, these packages should: - contain at least 4 useful functions (depending upon your team size, there should be at minimum one function per team member) that handle errors gracefully - be well documented - have unit and integration tests - use GitHub actions for continuous integration (with a passing build stamp in the README) - have a Software Licence that describes how you will permit others to use your work - have a code of conduct document that describes behavioural expectations of team interactions - have a contributions document that outlines how the team will work together (expected workflow practices) - have a Git history that demonstrates the proposed workflow in the CONTRIBUTING.md file was followed and that all group members contributed equally - demonstrate the GitHub issues were used effectively for project communication, organization and management (e.g., GitHub milestones and project boards should be used)

Milestone 1 summary

In this milestone, you will:

  1. Draft a team work contract
  2. Choose a topic for your software package
  3. Create project structure for the software package
  4. Write function specifications and documentation
  5. Manage issues professionally

Resources to help you on your way:

1. Draft a team work contract

Similar to what you did in DSCI 522, create a team-work contract. The contract should outline how you are committed to work together so that you are accountable to one another. Again, you may start with your team contract document from 522 and adapt it for your new team. It is a fairly personal document and please do not push it into your public repositories.

In writing this, we recommend reflecting on what went well and what didn’t go well in your last group project, and incorporating new ways of working in this team work contract to improve your group project experience this block.

2. Choose a topic for your software package

As a team, collaboratively come up with a topic for your software package.

3. Create project structure for the software package

  • Create the project structure for your software package, and push it as a public repository in the UBC-MDS organization on Github.com. There is a quickstart guide for setting up the structure for Python project, you can find it here. This time when you are prompted as whether to include GitHub Actions, say yes! In particular, choose option 3 (build + deploy).

  • The name of the repository should be relevant to the package/project topics.

  • During project creation, you will be prompted to pick a license and for now choose the MIT license. You may change it later when you learn more about licenses.

  • Once the projects have been created, add a section to the README.md file called ## Contributors and listing the contributors’ names there (i.e., the names of the members of your student team).

  • Edit CONDUCT.md to include the code of conduct for contributing to your project. The intention behind creating this file is fostering a healthy and positive work dynamic. Recall that you already have done something similar in DSCI 522, and you can start with that document and adapt it for your new team. Note that when you create the project structure with the methods above, a default version of this file will be created. You may choose to use it or adapt it with appropriate attributions.

  • Agree upon a collaboration strategy that describes how you will work together on this project (e.g., GitHub flow and edit CONTRIBUTING.md to reflect your strategy. Again, there will be a default version of this file. You can use it as is or adapt it with appropriate attribution. Here are some example CONTRIBUTING.md files for your reference.

  • Outline the package you would like to build in the README.md file. In particular, your README.md should contain:

    • a summary paragraph that describes the project at a high level
    • a bulleted list of the functions (and datasets if applicable) that will be included in the package (this should be a 1-2 sentence description for each function/dataset)
    • a paragraph describing where your packages fit into the Python ecosystem (are there any other Python packages that have the same/similar functionality? Provide links to any that do. If none exist, then clearly state this as well).

4. Write function specifications and documentation

For this milestone you will write function documentation that will serve as specifications (e.g., a function definition with function and argument names), but you will NOT write any code for your package functions. Specifically, set-up empty functions (with appropriate function names) containing no code in the files where you will eventually write code. Write function documentation (e.g., complete docstrings). These are the functions you wrote about in your README.md file.

Note: for your Python packages, because you have not written code or tests yet there will be many checks from the .github/workflows/*.yml file(s) that do not pass at this stage. This is fine and you can ignore them for now. We will work to have these checks pass in later milestones.

5. Manage issues professionally

Manage issues effectively through project boards and milestones, make it clear who is responsible for what and what project milestone each task is associated with. In particular, create an issue for each function in the package. Each of these issues must be assigned to a single person on the team. We want all of you to get coding experience in the project and each team member should be responsible for a package function. So if you are a team of four, you’ll be writing four functions for your package and if you are a team of three, you will be writing three functions for your package.

To ensure the TA’s can grade your project board, change the visibility from the default private setting to the public setting. To change the visibility of the project board do the following:

  1. Go to the project board and click on the three vertical dots on the right-hand side of the board and select settings

  2. Scroll to the bottom of the Settings page to the “Danger zone” and under visibility select “Public”.

Submission Instructions

You will submit a PDF to Gradescope for milestone 1 that includes:

  1. the URL of your software package’s GitHub.com repository
  2. the URL of a GitHub release of your software package’s GitHub.com repository
  3. a copy of your teamwork contract

Creating a release on GitHub.com

Just before you submit the milestone 1, create a release on your project repository on GitHub and name it exactly 0.0.1 (how to create a release). This release allows us and you to easily jump to the state of your repository at the time of submission for grading puroposes, while you continue to work on your project for the next milestone.

Expectations

  • Everyone should contribute equally to all aspects of the project (e.g., code, writing, project management). This should be evidenced by a roughly equal number of commits, pull request reviews and participation in communication via GitHub issues.
  • After the repository is set-up, each group member should work in a GitHub flow workflow; where they create branches for each feature or fix, which are reviewed and critiqued by at least one other teammate before the the pull request is accepted.
  • You should be committing to git and pushing to GitHub.com every time you work on this project.
  • Git commit messages should be meaningful. These will be marked. It’s OK if one or two are less meaningful, but most should be.
  • Use GitHub for project-related communication.
    • Use GitHub issues to communicate with team mates (as opposed to email or Slack).
    • Create project boards using GitHub and link tasks to issues.
    • Create GitHub milestones to group related issues. In particular, make a milestone for this milestone called milestone1 and put all the relevant issues linked to it.
  • Use proper grammar and full sentences throughout the project, especially in your README.