standards for cornell cup cs workflow and git
The Cornell Cup CS team is in the process of migrating its repositories and practices to a more efficient and clean state.
All repository names should be lowercase-with-dashes-as-separators.
Additionally, they should be tagged by their associated team or project. For example, cs-modbot.
Every repository should have a README.md file in the top level. This readme should include:
- A brief description of the purpose of the repository
- Clear, verifiable instructions on how to set up and run the project for the repository, if applicable.
The README is not a substitute for Confluence documentation.
Each repository has a tagline. This is what you see when viewing all repositories on the cornell cup. Taglines should serve as a brief but clear description of the repository.
Repositories should only have the files needed to run their project on them. Dependencies such as node_modules or extensive libraries such as OpenCV should be listed as a requirement and installed separately where appropriate.
Every repository should have a .gitignore unless it is clearly not needed (for example, this repository). The gitignore should serve to prevent anyone from pushing files that are clearly not needed (such as temporary build files).
All repositories which comply with the guidelines will be marked [clean] in the tagline. If a [clean] repository no longer complies with the standard, the tag should be removed and a git issue should be raised if appropriate.
When developing a new feature on a repo, whether or not you are using the full set of branching standards below, you should at least create a separate branch, work on that branch, and merge it back into the main branch when finished (ideally through a pull request).
Creating a new branch is as simple as typing
git checkout -b my_branch
This section is not necessarily required on every repository, though should be strongly considered.
In addition to other branches, repositories conforming to this standard will have a develop, rc, and a master branch.
The master branch serves as the last stable release of the repository's code. This facilitates easily building the code in case a prototype is needed.
The rc branch sits in between the develop and master branch. This is code that is meant for release but is still being tested.
The develop branch is the most up-to-date branch for reviewed code.
In order to add code to master, then, it must first go through develop. If you want to contribute code to a repository, then, you should follow this workflow:
- Fetch the most recent changes from the origin repository, then checkout to the develop branch.
- Checkout a feature branch with a descriptive name. For example, if the branch was for a waypoints feature, and we had an issue numbered 63 for waypoints, the branch would be called 63_waypoints.
- Develop on this feature branch until you feel the code is ready to be merged into develop.
- Push all of your code to Git, then create a Pull Request on GitHub. Make sure the base is set to develop and the merging branch is set to your feature branch.
- Wait for another team member to do a review of your code. If the team member makes any comments, address the issue by either fixing it or discussing it with the team member.
- When another team member is satisfied with the code, that team member will merge the code into develop.
When the manager of the repository wants to prepare the code for a release, the code from develop should be merged into rc, then end-to-end testing should be performed on the rc branch. If testing goes well, the code can be merged into master.
In summary, the workflow looks like this:
develop --Create Branch-> feature --PR-> develop --Prepare For Release-> rc --Tested-> master
TODO: In the future, we wish to set up a continuous integration server to ensure all code is tested and no changes cause issues. This is something a willing member can take up as a task.
While we are using Jira in order to track any tasks, GitHub Issues may be used to report small bugs if it is not appropriate on Jira.
All code pushed by you should be committed using your GitHub credentials in order to track code contributions and work.
Ordinarily, you can set this using
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
Most Cornell Cup computers include the script in this repository (cup-identify) for reminding you to do this.
We additionally have requirements specific to each repository. They are tracked in the language-specific folder of this repo. At the current time, we have specific requirements for:
- Java
- JavaScript
While this is a work in progress, this repository also contains tools for all CS computers to include. The .bashrc in this repo should be copied into every computer's bashrc and the tools folder should be linked. Note from the bashrc, this repo must be cloned until the local home directory.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent