Make it easy for someone to get started developing your project.
Make it easy for someone to run your project.
Articulate a testing plan.
Articulate your team's git workflow.
What to do
Create a directory named doc or docs in your
repository. The following documents should go there.
Write a document called development.txt or development.md
to provide step-by-step instructions for getting to the point of making a
change to your project and rebuilding it as a development collaborator. What to install, how to
launch the development tools with your project, etc.
Write a document called running.txt or running.md
to provide step-by-step instructions for running your application. In most
cases, this should not require installation of the development tools described
in the previous document. Just the shortest path to running your app.
Write a document called testing.txt or testing.md
to briefly describe a plan for testing your application. This should include a description
of automatic unit testing you plan to create, as well as types of tests that
you would execute manually.
Write a document called git-workflow.txt or git-workflow.md,
describing your partnership's agreement on when to branch, how to merge, and
whether code review is required before merging (e.g., via the GitHub Pull Request
mechanism).
Miscellaneous guidance
I will evaluate your development document by following
the steps you describe on my own computer (or on cs347.mathcs.carleton.edu, if that's your
guidance). If the steps are pretty easy to execute and I end up looking at
your code and ready to build it in whatever your development tool is, then I'll be
happy.
I will evaluate your running document similarly. My hope is
that after some simple step-by-step work, I'll be able to play with your app
in whatever state it's in at the time.
If your project has a Linux server-side component, I want you
to represent it with a Dockerfile, which will dramatically simplify
the running instructions.
Don't do full installation tutorials. For example, "install postgres" and
"create a database named animals" are appropriately granular steps.
If I need
to install data in a database, please provide it to me in an easily used form
such as the output of pg_dump or something similar.
We'll talk in class about unit tests. Some of the projects will be easy
to develop unit tests for. Others will be harder.