General Github workflow for lightweight team Work

Pull request review

Follow general Github guidelines, e.g. this one for submitting and maintaining your PR.

For code review process, Google's guide is pretty good, but we can lower the expectation sometimes based on other factors.

Finally, "Rebase and commit" is recommended over "Squash" or "Merge" since it is better to make your proposed commits show the changes your want to make at first place. You may use "Squash" if your personal git workflow is more liberal and don't want to do a lot of local commit edits. Normally this choice is not very important.

Branch protection

For any project, the branch protection of master should be open with default setting to avoid accidental force-push. Optionally, "Require linear history" is recommended to avoid merge commits that clusters the commit history.

If worked on by more than one person, to avoid creating problems for other people, CI should be set up and then enable "Require status checks to pass before merging". Also, check "Include administrators".

If worked on actively by more than one person, consider check "Require pull request reviews before merging" and ask your peer for review before getting new code in.

Testing and CI

Testing is essential in every stage of your project. Try to leverage on standard testing frameworks to write unit tests and aggressively create regression/end2end tests.

CI should be set up as soon as the project is worked on by more than one people. Github actions are usable as of now, despite lacking some features. Travis and Circle CI provide more features.

Design Review

For research or a quick prototype with no business requirements, it is normally quite costly and unnecessary to write a full design doc and conduct a complete design review. However, we should still try to do it in a light way by taking advantage of Github issue and other doc/communication channels to help us think before action and also get others' feedback. There is no template for this, but you should try to do it as much as possible within existing constraints.

Documentation

The best documentation is the code itself (actually further more in how you name each directories and structure them etc.). For code, naming your variables properly and writing clear code is important for showing its purpose and mechanism. You don't have to make it perfect for a light-weight project, but you should take another look at the code you are going to commit and ask yourself whether you can spend a few minutes to make it better for everyone who might use it one day. You can learn more from Google's code style guide (notice that most of them are quite specific and sometimes too strict. You should focus on the engineering principles behind it)

Document your code inline as much as possible, and try to follow each language's standard doc format such that IDE and doc generator can show your documentation conveniently.

Keep high-level stuff in separate Markdown documents, e.g. in docs/. Github wiki can work too. There is not much requirement on this, since they are hard to keep updated anyway. Just try to write more of them when you know everything.