CONTRIBUTING.md

   1 ## Contributing to Git Large File Storage
   2
   3 Hi there! We're thrilled that you'd like to contribute to this project. Your
   4 help is essential for keeping it great.
   5
   6 Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE.md).
   7
   8 This project adheres to the [Open Code of Conduct](./CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code.
   9
  10 ## Feature Requests
  11
  12 Feature requests are welcome, but will have a much better chance of being
  13 accepted if they meet the first principles for the project. Git LFS is intended
  14 for end users, not Git experts. It should fit into the standard workflow as
  15 much as possible, and require little client configuration.
  16
  17 * Large objects are pushed to Git LFS servers during git push.
  18 * Large objects are downloaded during git checkout.
  19 * Git LFS servers are linked to Git remotes by default. Git hosts can support
  20 users without requiring them to set up anything extra. Users can access
  21 different Git LFS servers like they can with different Git remotes.
  22 * Upload and download requests should use the same form of authentication built
  23 into Git: SSH through public keys, and HTTPS through Git credential helpers.
  24 * Git LFS servers use a JSON API designed around progressive enhancement.
  25 Servers can simply host off cloud storage, or implement more efficient methods
  26 of transferring data.
  27
  28 You can see what the Git LFS team is prioritizing work on in the
  29 [roadmap](./ROADMAP.md).
  30
  31 ## Project Management
  32
  33 The Git LFS project is managed completely through this open source project and
  34 its [chat room][chat]. The [roadmap][] shows the high level items that are
  35 prioritized for future work. Suggestions for major features should be submitted
  36 as a pull request that adds a markdown file to `docs/proposals` discussing the
  37 feature. This gives the community time to discuss it before a lot of code has
  38 been written. Roadmap items are linked to one or more Issue task lists ([example][roadmap-items]), with the `roadmap` label, that go into more detail.
  39
  40 [chat]: https://gitter.im/git-lfs/git-lfs
  41 [roadmap]: ./ROADMAP.md
  42 [roadmap-items]: https://github.com/git-lfs/git-lfs/issues/490
  43
  44 The Git LFS teams mark issues and pull requests with the following labels:
  45
  46 * `bug` - An issue describing a bug.
  47 * `core-team` - An issue relating to the governance of the project.
  48 * `enhancement` - An issue for a possible new feature.
  49 * `review` - A pull request ready to be reviewed.
  50 * `release` - A checklist issue showing items marked for an upcoming release.
  51 * `roadmap` - A checklist issue with tasks to fulfill something from the
  52 [roadmap](./ROADMAP.md)
  53
  54 ## Branching strategy
  55
  56 In general, contributors should develop on branches based off of `master` and pull requests should be to `master`.
  57
  58 ## Submitting a pull request
  59
  60 0. [Fork][] and clone the repository
  61 0. Configure and install the dependencies: `make`
  62 0. Make sure the tests pass on your machine: `make test`
  63 0. Create a new branch based on `master`: `git checkout -b <my-branch-name> master`
  64 0. Make your change, add tests, and make sure the tests still pass
  65 0. Push to your fork and [submit a pull request][pr] from your branch to `master`
  66 0. Pat yourself on the back and wait for your pull request to be reviewed
  67
  68 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
  69
  70 * Follow the [style guide][style] where possible.
  71 * Write tests.
  72 * Update documentation as necessary.  Commands have [man pages](./docs/man).
  73 * Keep your change as focused as possible. If there are multiple changes you
  74 would like to make that are not dependent upon each other, consider submitting
  75 them as separate pull requests.
  76 * Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
  77
  78 ## Building
  79
  80 ### Prerequisites
  81
  82 Git LFS depends on having a working Go 1.7.3+ environment, with your standard
  83 `$GOROOT` and `$GOPATH` environment variables set.
  84
  85 On RHEL etc. e.g. Red Hat Enterprise Linux Server release 7.2 (Maipo), you will neet the minimum packages installed to build Git LFS:
  86
  87 ```
  88 $ sudo yum install gcc
  89 $ sudo yum install perl-Digest-SHA
  90 ```
  91
  92 In order to run the RPM build `rpm/build_rpms.bsh` you will also need to:
  93
  94 `$ sudo yum install ruby-devel`
  95
  96 (note on an AWS instance you may first need to `sudo yum-config-manager --enable rhui-REGION-rhel-server-optional`)
  97
  98 ### Building Git LFS
  99
 100 The easiest way to download Git LFS for making changes is `go get`:
 101
 102     $ go get github.com/git-lfs/git-lfs
 103
 104 This clones the Git LFS repository to your `$GOPATH`. If you typically keep
 105 your projects in a specific directory, you can symlink it from `$GOPATH`:
 106
 107     $ cd ~/path/to/your/projects
 108     $ ln -s $GOPATH/src/github.com/git-lfs/git-lfs
 109
 110 From here, run `make` to build Git LFS in the `./bin` directory. Before
 111 submitting changes, be sure to run the Go tests and the shell integration
 112 tests:
 113
 114     $ make test          # runs just the Go tests
 115     $ cd t && make test  # runs the shell tests in ./test
 116     $ script/cibuild     # runs everything, with verbose debug output
 117
 118 ## Updating 3rd party packages
 119
 120 0. Update `glide.yaml`.
 121 0. Run `make vendor` to update the code in the `vendor` directory.
 122 0. Commit the change.  Git LFS vendors the full source code in the repository.
 123 0. Submit a pull request.
 124
 125 ## Releasing
 126
 127 If you are the current maintainer:
 128
 129 * Create a [new draft Release](https://github.com/git-lfs/git-lfs/releases/new).
 130 List any changes with links to related PRs.
 131 * Make sure your local dependencies are up to date: `make vendor`
 132 * Ensure that tests are green: `script/cibuild`
 133 * Bump the version in `lfs/lfs.go`, [like this](https://github.com/git-lfs/git-lfs/commit/dd17828e4a6f2394cbba8621037199dc28f046e8).
 134 * Add the new version to the top of CHANGELOG.md
 135 * Build for all platforms with `make release` (you need Go setup for
 136 cross compiling with Mac, Linux, FreeBSD, and Windows support).
 137 * Test the command locally.  The compiled version will be in `bin/releases/{os}-{arch}/git-lfs-{version}/git-lfs`
 138 * Get the draft Release ID from the GitHub API: `curl -in https://api.github.com/repos/git-lfs/git-lfs/releases`
 139 * Run `script/release -id {id}` to upload all of the compiled binaries to the
 140 release.
 141 * Publish the Release on GitHub.
 142 * Update [Git LFS website](https://github.com/git-lfs/git-lfs.github.com/blob/gh-pages/_config.yml#L4)
 143 (release engineer access rights required).
 144 * Ping external teams on GitHub:
 145   * @github/desktop
 146 * Build packages:
 147   * rpm
 148   * apt
 149 * Bump homebrew version and generate the homebrew hash with `curl --location https://github.com/git-lfs/git-lfs/archive/vx.y.z.tar.gz | shasum -a 256` ([example](https://github.com/Homebrew/homebrew-core/pull/413/commits/dc0eb1f62514f48f3f5a8d01ad3bea06f78bd566))
 150 * Create release branch for bug fixes, such as `release-1.5`.
 151 * Increment version in `config/version.go` to the next expected version. If
 152 v1.5 just shipped, set the version in master to `1.6-pre`, for example.
 153
 154 ## Resources
 155
 156 - [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/)
 157 - [Using Pull Requests](https://help.github.com/articles/using-pull-requests/)
 158 - [GitHub Help](https://help.github.com)
 159
 160 [fork]: https://github.com/git-lfs/git-lfs/fork
 161 [pr]: https://github.com/git-lfs/git-lfs/compare
 162 [style]: https://github.com/golang/go/wiki/CodeReviewComments