github.com/quickfeed/quickfeed@v0.0.0-20240507093252-ed8ca812a09c/README.md (about) 1 # QuickFeed: Instant Feedback on Programming Assignments 2 3 [](https://github.com/quickfeed/quickfeed/actions) 4 [](https://goreportcard.com/report/github.com/quickfeed/quickfeed) 5 [](https://codecov.io/gh/quickfeed/quickfeed) 6 [](https://github.com/quickfeed/quickfeed/actions) 7 8 ## Documentation 9 10 - Teachers that wants to use QuickFeed may wish to review the [User Manual](doc/teacher.md). 11 - Teachers may also want to copy the [sign up instructions](doc/templates/signup.md) and [lab submission instructions](doc/templates/lab-submission.md), and make the necessary adjustments for your course. 12 - [Installation instructions for QuickFeed](doc/deploy.md). 13 14 ### Install Development Tools 15 16 On Unix systems with homebrew you should be able to install development tools using: 17 18 ```shell 19 % make brew 20 % make devtools 21 # Make sure the bin folder with our tools is in your PATH. 22 % export PATH=$PATH:$PWD/bin 23 ``` 24 25 For non-brew users, please inspect the `Makefile` to determine instructions for your system. 26 27 ## Contributing 28 29 The following instructions assume you have installed the [GitHub CLI](https://github.com/cli/cli). 30 See here for [installation instructions](https://github.com/cli/cli#installation) for your platform. 31 32 Further, we require that code is formatted according to the rules and extensions that have been configured for VSCode. 33 When opening VSCode, please install the recommended extensions for QuickFeed; [see also style guidelines below](#style-guidelines). 34 Specifically, you will need to install the `clang-format` tool to edit `.proto` files, and the `golangci-lint` tool to edit `.go` files. 35 36 ### Create Issue First 37 38 Before you implement some feature or bug fix, you should open an issue first. 39 This issue should then be linked in the corresponding pull request. 40 41 ### Create Pull Request 42 43 Before starting a new pull request, either clone the repo: 44 45 ```shell 46 % gh repo clone quickfeed/quickfeed 47 % cd quickfeed 48 ``` 49 50 Or if you have already cloned, make sure to start from an up-to-date master branch: 51 52 ```shell 53 # Make sure to start from master branch 54 % git checkout master 55 # Make sure your master branch is up-to-date 56 % git pull 57 ``` 58 59 To create a pull request on the main repository follow these steps. 60 61 ```shell 62 # Create and switch to your new feature branch 63 % git switch -C <feature-branch> 64 # Edit and stage files 65 % git add <files> 66 % git commit 67 # When done and ready to share 68 % gh pr create --title "Short description of the feature or fix" 69 # Alternatively: Use --draft if you want to share your code, but want to continue developing 70 % gh pr create --draft --title "Short description of the feature or fix" 71 ``` 72 73 To continue development on a pull request (same branch as before): 74 75 ```shell 76 # Only necessary if you previously switched away from the feature-branch 77 % git switch <feature-branch> 78 # Edit and stage files 79 % git add <files> 80 % git commit 81 % git push 82 ``` 83 84 To fetch an existing pull request to your local machine. 85 86 ```shell 87 % gh pr checkout <PR#> 88 ``` 89 90 For additional details on the `gh pr` and `gh pr create` commands: 91 92 ```shell 93 % gh help pr 94 % gh help pr create 95 ``` 96 97 ### GitHub Issues and Pull Requests 98 99 When creating a pull request, it is always nice to connect it to a GitHub issue describing the feature or problem you are fixing. 100 If there is an issue that is fixed by your pull request please remember to add one of the following lines at the end of the pull request description. 101 102 ```text 103 Closes <Issue#>. 104 Fixes <Issue#>. 105 Resolves <Issue#>. 106 ``` 107 108 For detailed instructions on configuring QuickFeed for development, please see our [Developer Guide](doc/dev.md). 109 110 ### Style Guidelines 111 112 We chose to implement QuickFeed in Go and Typescript because these languages offer simplicity and type safety. 113 We therefore require that certain style guidelines are followed when creating pull requests. 114 115 For Go, we expect code to follow these style guidelines and list of common mistakes: 116 117 - We use the `golangci-lint` linter in VSCode. 118 119 - [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments). 120 In particular, note the section on how to 121 [Handle Errors](https://github.com/golang/go/wiki/CodeReviewComments#handle-errors), 122 [Mixed Caps](https://github.com/golang/go/wiki/CodeReviewComments#mixed-caps), 123 [Variable Names](https://github.com/golang/go/wiki/CodeReviewComments#variable-names). 124 125 For Typescript, we think these [style guidelines](https://github.com/basarat/typescript-book/blob/master/docs/styleguide/styleguide.md) look reasonable. 126 Moreover, the `formatOnSave` and `tslint.run` options in VSCode should help maintain reasonable style. 127 128 Note that we currently violate the [interface naming](https://github.com/basarat/typescript-book/blob/master/docs/styleguide/styleguide.md#interface) 129 guideline by using the `I` prefix on some interfaces, and several of the other guidelines. 130 We have started to rename these interfaces, and will eventually rename all such interfaces.