DPS909/OSD600 Fall 2018 Release 0.1
Contents
Release 0.1
Due Date
Friday September 28th. 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 improve test coverage for 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. Recently, node.js has added new features to the fs module which need to be ported to, and fully tested (i.e., unit tests) in Filer.
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, specifically node.js and Filer
- working with branches, commits and other aspects of git
- creating Pull Requests in GitHub
- filing, triaging, and working with Issues on GitHub
- writing and running automated unit tests, specifically using mocha, karma, and puppeteer
- 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.
There are thousands of automated unit tests in node.js, which allow the expectations of the interfaces node uses to be checked against the implementations. Similarly, Filer has hundreds of tests, and in an ideal world, the same types of logic and examples being tested in node should also be tested (and work!) in Filer.
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
Recently, a Pull Request was merged in Filer adding support for the new fsPromises API. However, no tests were added with the code. We now need to add tests for all aspects of this new API.
You are asked to find one thing that needs to be tested as is currently not. For example, you might test to make sure that performing a series of steps with the fsPromises API works as expected (files are created or deleted or altered as you expect). You are encouraged to study the node.js tests for ideas.
When you file your bug, 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). When you file your bug, make sure you include enough information to make it clear what the problem is. For example, "Add test case for using f() when x and y are true." You can include links to code you find in node, or snippets of code you have written yourself that demonstrate what is going on.
If you wish to work on this bug, make sure you indicate that as well. For example, you might file more than one bug, but not work on solutions for all of them, leaving the problems to other students.
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)
- Adds a Test, and/or Code Fix, and/or Documentation update
- 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.
