Git/SymPy Project
Video
Motivation
Today we are going to simulate two common git workflows - collaborating with your colleagues, and contributing to open source projects.
This is going to be a bit of a break from our regularly scheduled lecture - we will be breaking out into zoom breakout rooms for the lecture.
Assignment
Your assignment is to, as a group, make changes to the example project.
Fork & Directory Setup
Yesterday, you should have:
-
Selected a host, who:
- Used GitHub's fork button to create a copy of the group project repository.
- Used GitHub's project settings to invite the other collaborators to the project.
- Helped verify that all group members understand the steps necessary to create a fork and add collaborators.
-
Each User also should have:
- Joined the project by going to the invitations page
https://github.com/{host username}/OnlineMathSolverExample/invitations - Added their
id_rsa.pubfile to their GitHub Account - Cloned the repository to a local directory.
- Checked their Git Remotes with
git remote -vto make sure you have push and fetch access to your project host's GitHub fork of the project
- Joined the project by going to the invitations page
Once this prep-work is complete, you can move on to the work.
Setting Up Your Local Environment
Projects often require other software that isn't bundled together. These requirements files are language-specific, but for Python, the standard file is called requirements.txt.
Within the project directory, open up requirements.txt. In this case, it lists:
Flask>=1.0
sympy>=1.4
This sets a minimum version for Flask and sympy.
To install the requirements with pip, you can run the command:
pip install -r requirements.txt
or with Anaconda:
conda install --file requirements.txt
Creating a Project-Specific Environment
We haven't gone into much detail about environments, but basically they are fresh installations of Python. It is often good practice to use them when developing software to share.
You can create virtual environments in Anaconda, or with the venv stdlib module. It is recommended - if you store the environment in the project - to add it to your .gitignore so as not to share out of date or redundant code.
Exploring The File
Now that you have everything you need, you can run the file:
python solver_website.py
This will create a local server, which you can connect to by http. By default, it launches on Port 5000 if the port is unused, but it will tell you where it launched.
Play around a bit, and look in the actual files to get a feel for the process.
Starting Development
Now divide up the unimplemented functions between your team, so that each person has at least one function. It is OK to not implement them all - so long as everyone does one themselves.
Create a branch with a descriptive name for the issue you are solving. For example:
git checkout -b linear_solver
Create incremental commits each time you get a portion of your function working how you like it, and don't be afraid to roll back to a previous commit if you make a change you don't like.
Writing Tests
For some functions - especially ones that involve formatted responses - prescriptive tests (written before the function) are hard.
For testing these functions, you can get the function working first - then run examples in an interactive session, and copy their output for your tests. This will help verify that the function continues working well, even if underlying technologies change.
When You (individually) Finish
Once you are done, merge your changes into master:
git checkout master
git merge linear_solver
Resolve any merge conflicts that arise, and don't forget to push the changes to your group!
When You (collectively) Finish
When your group is done, find a time to go through the pull request proccess together.
In your group fork on GitHub, click the "Pull requests" tab:
And then the "New Pull Request" button:
Create a pull request from your master to the upstream master, and give it a relevant title and description. the title should include at the end a list of issues resolved; for example:
resolves ClintonWB/OnlineMathSolverExample#1, resolves ClintonWB/OnlineMathSolverExample#3
In the Pull Request notes, list the names of your group members next to which function they contributed to the final product.
The function
git shortlog
Is useful for creating summaries of who did what; edit its output, or play around with its options, to show who did what parts.
Submit your pull request, and you will be done with this exercise.
Contributing to Other Projects
Congratulations! This process - from issue, to fork, to pull request - is used widely to contribute to open source projects large and small. Consider giving back to software that has helped you!
Many projects could use some help on simple documentation writing/updates, or on other issues that are good first issues. They will likely be tagged - jump in and help out!