DPS909/OSD600 Fall 2017 Lab 6/7
Contents
- 1 Introduction: GitHub Repos and Pull Requests
- 2 Step 1: Design a Library for Obtaining File Info
- 3 Step 2: Pick a Language
- 4 Step 3: Pick a License
- 5 Step 4: Look for Existing Modules/Libraries/Packages to Help
- 6 Step 5. Create a Repo on GitHub
- 7 Step 6. Clone your Repo Locally
- 8 Step 7. Plan your Library by Filing Issues
- 9 Step 8. Start coding
- 10 Step 9. Publish your master branch
- 11 Step 10. Invite people in the Class to Contribute
- 12 Step 11. Contribute to Another Project
- 13 Step 12. Code Review
- 14 Step 13. Record your Contribution(s)
- 15 Step 14. Blog
- 16 Submission
Introduction: GitHub Repos and Pull Requests
This lab is all about practicing the git/GitHub workflow we discussed on Tuesday. By the end of this lab, you will have successfully done the following:
- Created a new repo for a project
- Written new code, committed it locally, and pushed it to GitHub
- Contributed a Pull Request to another student's repo
- Reviewed and Merged a Pull Request from another student to your repo
This process will give you some exposure to the entire process of creating, maintaining, and contributing to an open source project.
We'll spend a couple weeks doing this lab, so take your time and don't rush this learning.
If you have trouble with any of the steps below, or need help, please use our Slack channel to ask your questions. Don't suffer in silence.
Step 1: Design a Library for Obtaining File Info
You are asked to create a new open source library. A library/package/module/etc is a collection of functionality that can be used by an application developer to accomplish a set of tasks. NOTE: I don't need you to write a full application; just a library of functions.
The purpose of this library is to make it easy to get various pieces of info about a given file on disk. You will write functions in your library that return the following:
- filename without path. For example: given a path like
"/home/kim/mydata.txt", return"mydata.txt" - file size in bytes. For example, given a path like
"/home/kim/mydata.txt", return129(e.g., the file is 129 bytes on disk) - sha1 digest for a file at the given path. For example, given a path like
"/home/kim/mydata.txt", which contains the textThe quick brown fox jumps over the lazy dog, return2fd4e1c67a2d28fced849ee1bb76e7391b93eb12 - MD5 digest for a file at the given path. For example, given a path like
"/home/kim/mydata.txt", which contains the textThe quick brown fox jumps over the lazy dog, return9e107d9d372bb6826bd81d3542a419d6
There are various online tools you can use to generate digests for SHA-1 and MD5 while testing, for example http://www.sha1-online.com/.
Step 2: Pick a Language
You can write your library in any language you want. Consider choosing a language you don't usually use, or have never used before and want to learn. Challenge yourself to learn something new, and push yourself out of your comfort zone. You aren't being marked on the quality of your code, this is just a learning exercise. Here are some suggestions:
- JavaScript (or TypeScript) and node.js
- Python
- Rust
- Go
- Swift
When you choose your language, remember that you are going to need to convince another student to contribute to your repo, and shouldn't pick something that no other developer uses or wants to learn. This is true of all open source projects. Choose wisely!
NOTE: GitHub published numbers on language popularity yesterday.
Step 3: Pick a License
Pick a license for your project. You can use any open source license you want. Be careful what you choose, since you don't want to limit your ability to use existing code (e.g., make sure you pick something that can be combined with other open source licenses).
If you're not sure what to pick, consider using BSD, MIT, or Apache.
Step 4: Look for Existing Modules/Libraries/Packages to Help
You can use any existing open source code that will help you write your library. For example, if you can find a module that already implements the MD5 digest algorithm, use it. Don't write any code you don't have to, don't reinvent the wheel.
Make sure that any open source code you choose is compatible with the license you've chosen. You may need to adjust your license or language choice depending on what you find.
Step 5. Create a Repo on GitHub
Follow the instructions on GitHub to create a repo for your library. Make sure you choose a name that hasn't already been used by another project, company, or product. Try doing a Google search before you settle on your name.
Step 6. Clone your Repo Locally
Clone your repo on your local computer.
Step 7. Plan your Library by Filing Issues
Begin by planning your work as a series of Issues in GitHub. Each issue should be small enough to capture a single feature, improvement, or task. For example, you might file issues for each of the main functions of your library. You might also choose to break those down into a smaller issues. Do what feels right for you. Fixing many small bugs is often easier than a few large ones.
Step 8. Start coding
Now that you have issues filed, pick one and start coding it. Remember to do each fix on a separate branch. Once you get a feature finished, and you're happy with it, you can merge it into your master branch. Here's an example of what this might look like:
git checkout -b issue-1 ...write the code... git add <filename> git commit -m "Fix #1: Added code to do feature X" git checkout master git merge issue-1
Step 9. Publish your master branch
When you've got a few of your bugs fixed and merged into master, it's time to publish your work on GitHub. To do this, you want to push your master branch:
git checkout master git push origin master
Now visit your GitHub repo and make sure you can see your commits, and the code you've written. If anything looks wrong, do another commit to fix it, and push again.
Step 10. Invite people in the Class to Contribute
When you're ready to have people contribute to your project, add your name and GitHub Repo URL to the table below. File any additional Issues in your project repo on GitHub for things you'd like help doing (see suggestions in step 11 below). You can also use the Slack channel to tell people about your project, and how they can get involved.
Step 11. Contribute to Another Project
In addition to creating and maintaining your own library, you are asked to contribute to at least one other project in the class. You can work on a different language than you wrote your own project using, and are free to work with anyone in the class (e.g., don't limit yourself to people you know).
Here are some suggestions of things you could do:
- Write the README.md file, with instructions on how to setup and use the library
- Add automated tests (e.g., unit tests) to make sure the library does what it's supposed to do
- Add automated code quality checks (e.g., linting) to help find bugs before they happen
- Add a build system to make it easier to perform common tasks (e.g., build or minify the code, run tests, do various checks)
- Write a simple command line tool shows an example of how you use the library
- Improve the code to make it cleaner, faster, or more simple (e.g., remove duplication, add documentation)
- Test the code and fix a bug if there are any. Does the code do the right thing in all cases? What happens if you give it data that's different from how the original author wrote it (e.g., run the code on macOS or Linux instead of Windows)?
Before you contribute to another project, make sure there is either an existing bug, or file one yourself. Make sure the project owner knows you're working on this issue.
Next, fork and clone their repo. Create a branch for the issue you're fixing, make your changes, add, and commit. Then push your branch to your fork.
Finally, create a Pull Request for your change. In your Pull Request's description, make sure you use the pattern Fix #...: ... to have GitHub automatically close the associated issue when your Pull Request is merged. For example, if you are working on Issue 14, you might say, Fix #14: add md5 unit test. Also include a useful discussion of what you've done, how to test it, etc.
Step 12. Code Review
Every Pull Request will need to be reviewed by the project maintainer. When someone submit a Pull Request to your repo, you'll get an email. You should go and read their code, and make any suggestions for how you want it to be fixed (if necessary). Remember that as a maintainer, it's your job to help new contributors feel welcome and valued in your project--you want them to stick around and fix more bugs.
When you submit your own Pull Request, if there are changes requested, please make them and then commit and push your branch again. Any new commits will get added to the pull request. You should let your reviewer know when you've added more commits so that he/she can go and re-review your work.
When everything is complete, the maintainer will merge the pull request. When this happens, the commits on the branch will get added to master. The maintainer should then pull these commits to their local cloned repo:
git checkout master git pull origin master
Step 13. Record your Contribution(s)
Once you've submitted one or more Pull Requests, make sure you add links in the table below beside your name.
Step 14. Blog
Write a blog post about your experiences in this lab. In particular, discuss each of the following:
- Why did you choose the language you chose? What did you think of it? Would you use it again?
- Were you able to find any existing open source code that you could re-use? How did that go? Did you have any technical or licensing issues?
- What was it like contributing to another project?
- What was it like having people contribute to your project?
- Did you learn anything during your own experience as a maintainer or contributor that will impact you when you do this again?
- Did you run into any issues with git as you managed your project? What did you learn in the process, and what do you still need to learn more about?
