Table of contents
TASing emulators make extensive use of emulator projects initially unrelated to TASing. Existing emulator cores often get forked to include TAS functionality. TASing emulators heavily depend on how those cores are being developed by the community. And the open source community happens to have moved from SVN to Git, therefore Git workflow is usually involved in developing TASing emulators.
Main project
- When committing to the branch that several people are using, don't use merge, use fetch/rebase.
- For significant and important changes, make pull requests and ask for code review.
- Never merge a pull request without actually making sure it's good.
- Sometimes it might be acceptable to let the users test something new and figure out if it has problems, but adding critical bugs to releases is also highly possible! So do the checking.
- Always demand that coding conventions are met. This also implies those must exist!
- Use Squash when it fits.
- Set up automatic building for commits (at least for master/main and pull requests). This allows to always have the latest build available.
- Enforce code style, possibly in some automated way that's not too hard to set up and is accurate.
- TODO: Make sure to follow renames and copies.
- Don't underestimate bisect!
Forking
Git is really powerful and quite complicated, so it requires a lot of paperwork to keep things clean, but if you do it consistently, you can always be sure everything is perfectly clean.
- Fork the project to the appropriate organization.
- Set up "upstream" remote to always be able to easily pull updates from the original project.
- Keep the "master" branch intact. That way it's easier to pull upstream changes, and allows to always have a clean backup branch. Also helps to keep the pull requests clean.
- Do the needed diverging work in separate branches.
- There should be the main branch that the fork exists for (not to be confused with upstream's main branch). That branch would be used directly by the main TASing emulator project and have all the needed feature branches merged.
- Each bug-fix to upstream should come from its own branch.
- If some edit relevant to TASing is possible to send upstream, it should always be done. Separated branches help to isolate work that can be potentially sent upstream. Ideally there would be no need to support diverging features compared to upstream. This means all the TAS related features are refined and sent as pull requests to the original project, and then no branch dedicated to TASing would be needed.
- The fork should be included in the main project repository as a submodule. This allows to have a pointer to a specific branch and commit that's guaranteed to work with the main project, and updating this pointer is saved in the main project history.
- TODO: Submodules require a bit of paperwork overhead, so list all the safeguard steps here.
- Duly incorporate upstream changes. Keeping up-to-date is very important in the long run, after some time it might be too hard to update.
- It makes sense to rebase (rather than merge) your fork's edits on top of all upstream updates every time you update.
- Rebasing means you will need to have versions of your main branch, based on new master, with rebased feature branches merged from scratch.
- If some of your features breaks as a result of update, a fix should be squashed with the past commit that is now breaking it.
Commands
This is how fork branches are managed:
git checkout master
git pull upstream/master
git push master
git checkout [feature_branch]
git rebase master
git checkout master
git checkout -b [main_branch_version_N]
git merge [feature_branch]