OSD & DPS909 Winter 2019 Release 0.1
Contents
Release 0.1
Due Date
Wednesday January 30th. See Requirements below for details on what needs to be included in your submission.
Overview
This first release is designed to expose you to the common workflows and tools involved in contributing to open source projects on GitHub. In order to give every student a similar learning experience, we will all be working on the same project and code. NOTE: in subsequent releases, students will have more freedom to contribute to other projects.
Our goal will be to modernize code in the Filer web filesystem project. Filer implements the node.js fs module, providing a way to read, write, and manipulate files and directories in web pages using IndexedDB as a backing data store.
The code was written before some modern syntax in JavaScript was common, and it needs to be updated.
Learning Goals
In addition to the actual code you will write, the ultimate goal of this first release is to help you gain experience in many aspects of open source development and contribution, specifically:
- reading and searching through existing code
- working with branches, commits and other aspects of git
- creating Pull Requests in GitHub
- filing, triaging, and working with Issues on GitHub
- running automated unit tests, specifically using mocha and karma
- working with static analysis tools, specifically eslint
- continuous integration and automation, specifically using Travis CI
- working in an open source community
- reviewing other contributor's Pull Requests
- using open communication tools, such as Slack
- writing about your own work via your Blog
Technologies
Web pages are sandboxed from the operating system, and normally there is no way to work with files and directories. However, many existing applications rely on access to a full filesystem, for example, editors. Anyone wanting to create a web application that needs to work with files and directories can use Filer, and the data will persist between sessions.
Filer shares no code with node.js, since node is meant to be run directly in an operating system vs. a browser. Instead, Filer implements the same interface (i.e., set of functions and objects) as the fs module, making it possible for developers to port an application from working only on node, to working in the browser as well.
Filer uses mochajs and the chai expect assertion library for its tests. Most of the tests are located in tests/spec. The complete list of tests that gets run is located in tests/index.js. NOTE: if you add a new test file, it needs to get added to this file as well.
Details on how to setup and run the tests are available in CONTRIBUTING.md.
Filing an Issue
Modern JavaScript prefers let and const to var for creating variables and constants:
- When should you use const and let instead of var in JavaScript?
- JavaScript's var, let, and const variables explained with a story
- MDN docs on const
- MDN docs on var
- MDN docs on let
- MDN docs on strict mode
Filer currently uses var almost everywhere. We should update the code to use let and const and strict mode.
You are asked to pick a file in the tests/ directory and update the code to use modern variable creation, as well as strict mode.
Before you begin, file a new Issue in GitHub. When you file your Issue, you should first make sure that no one else has already filed the same thing. This is known as a "dupe" (i.e., a duplicate bug). Make sure you include enough information to make it clear what the problem is. For example, "Update code in tests/some/file.js to use const/let."
Fixing Your Issue
Once your issue is filed, begin your fix by forking Filer and creating a new branch. You must create a new branch before you commit any code or submit a pull request. If your Issue was #123, create a branch named issue-123.
Make sure you can run the existing tests, and that they all pass. You want to make sure everything is working before you begin
On your new branch, you can make as many commits as you need to. Don't worry if you make mistakes, or need to overwrite/undo something; just add more commits to fix the problems. If you need to add new test files, that's fine, or you might be able to add to an existing file. Also, do not merge any code into your branch. Leave that for the very end, when your fully reviewed and corrected pull request will (hopefully) get merged by a Filer maintainer.
Getting Help
At every stage of your work, make sure you ask for help, and get feedback from others in the community by asking questions. Don't struggle on your own and get stuck, or miss the due date.
Please use the Filer GitHub Issues and Open Source Slack.
Requirements
You will be graded on the following. Please make sure you have addressed everything that makes sense below:
- Proper Pull Request to Filer
- An Issue should be filed before your create your Pull Request. The Issue must have a complete subject and description of the problem or change you believe needs to be made.
- The Pull Request should reference the Issue Number in its description (e.g., "Fixes #123: Add test for ...")
- Changes must be made on a new branch (e.g., if you are fixing Issue 123, use issue-123 as your branch name)
- Proper code to fix your Issue
- Code or Tests must pass eslint
- All Unit Tests must pass after your changes are made (i.e., new tests must pass, and you must not break existing tests)
- Co-ordination with other student/community Pull Requests. Make sure you don't duplicate another fix or change that someone else has already done.
- Review of Another Student's Pull Request
- Compare the Pull Request to the related Issue it is trying to fix. Has everything been covered?
- Confirm that there are no other related Issues or Pull Requests that might conflict with this Pull Request
- Confirm that tests, code, and other automated tests run correctly and all pass
- Review code and other changes, making comments and suggestions about any improvements you can see, or other issues that need to be addressed
- Blog Post
- Discussion of the change(s) you made. What was your process? What did you learn? What would you do differently next time, or what worked and you would do again?
- Link to the Issue(s) you filed, and discuss the bug/problem/addition you wanted to address.
- Link to the Pull Request(s) you created, and discuss the fix.
- Link to the Pull Request(s) you reviewed, and discuss what you did and found.
- Discussion of what you did to address your review comments.
- Evidence of Community Involvement. Could be Issues you worked in to help others, help you gave people on Slack, mentoring or other help you gave people in person. How did you engage with the community of developers working on Filer?
- Add Info to Table Below
- Make sure you Name, Blog URL, Pull Request URLs, etc are all included
Submission
When you have completed all the requirements above, please add your details to the table below.
