Discussions provide some nice features for questions, including a way to
mark suggested answers and threading. Let's encourage users to use them
for things which are not bug reports or feature requests.
Let's also mention the FAQ in the CONTRIBUTING documentation, so that
users who are about to start a discussion but have a common question can
find their answer quickly. The README already has such an entry
directly above the text we've added.
We're going to want to rename the default branch to main, so let's
update our documentation so it reflects the right branch for users to
work with, for core team members to use for releases, and for the latest
version of the documentation.
The introductory paragraph used the phrase "keeping it great". A
similar phrase is used as part of a major political campaign, and we'd
like to avoid any political associations that one might draw from that,
since they're irrelevant and distracting.
Since we document in the README that we support the latest version of
Go, update the contributing documentation to reflect the same thing.
Mention that we try to avoid breaking support for older versions if
possible.
Add a section on issues that addresses a few common problems we see when
people report an issue. Encourage users to provide helpful debugging
information like the output of "git lfs env" and GIT_TRACE output, and
to use the troubleshooting section of the wiki to help pin down any
problems. Point out that opening a new issue is preferable to commenting
on a closed issue.
Mention that problems with GitHub are best addressed directly with
GitHub; these are things we aren't likely to be able address here, and
folks reporting them to GitHub are likely to get a better response and
quicker action.
Sometimes we get pull requests that have no description or rationale.
This makes it hard for maintainers to evaluate why the pull request is
needed and what problems it is intended to solve. Encourage users to
provide some explanation in the pull request and hinting that they may
use part (or all) of their good commit message to accomplish this goal.
Occasionally, we get feature requests for features that are risky or
dangerous and are prone to misuse by less experienced users. Mention
that we try to avoid features that are easy to misuse or are likely to
allow users to lose data easily.
ShellSession gives us marginally better highlighting, comparing
$ foo
$ bar
with:
```ShellSession
$ foo
$ bar
```
So, where appropriate, let's convert the former into the later.
Since the advent of [1], and [2], we use Go 1.11 with modules enabled.
This relieves us of the requirement of having Git LFS checked out within
the appropriate location beneath the caller's $GOPATH.
So, let's remove the guideline, and recommend away from using `go get`,
since this command behaves differently based on whether or not its CWD
is itself a Go repository.
Instead, recommend that we use `git clone`, and do not specify a
location to perform the clone in, since Git LFS can be checked out from
anywhere.
[1]: dfc0f2fc (Merge pull request #3298 from git-lfs/ttaylorr/go-1.11.1,
2018-10-08)
[2]: 35fe301c (Merge pull request #3208 from git-lfs/ttaylorr/go-mod,
2018-08-29)
We use the Markdown trick that the same number over and over again
produces a list of numbers incrementing starting at that base.
This is good, since it reduces the diff later on should the list
ordering change, grow new elements, etc. But it is not desirable to
start the list at zero.
Let's instead increment the list starting at 1, that way we get lists of
the form (1), (2), (3), instead of (0), (1), (2).
We no longer use the ROADMAP.md files; instead, we use milestones to
track the items we wish to work on for the next release. Update the
project management section to reflect other things we don't do anymore
as well, like use Gitter or roadmap issues.
Since we are now building on Go 1.11 (as of 074a2d4f (all: use Go 1.11
in CI, 2018-08-28)) and Go 1.11 supports Go Modules [1], let's stop
using Glide, and begin using Go Modules.
This involves a few things:
* Teach the Makefile how to build go.sum files instead of glide.lock
files.
* Teach continuous integration services to build Git LFS in a
non-$GOPATH environment, since (without setting GO111MODULE=on
explicitly, which we choose not to do), this will break compiling
Git LFS, because Go 1.11 will ignore modules present in a Go
checkout beneath $GOPATH.
* In order to do the above, let's also make sure that we are
un-setting $GOCACHE in the environment, as this causes Go to work
without modules support [2].
* Because we're no longer building in a `$GOPATH`-based location,
let's instruct the CircleCI base image to archive the new location,
too.
* Similarly, teach the RPM spec to build in a non-$GOPATH location.
* By contrast, since we use dh_golang to build git-lfs binaries on
Debian, let's wait until the upstream dh_golang package is released
with support for Go 1.11 module support explicitly. Therefore, force
GO111MODULE to be on so that we can build a copy of Git LFS whose
checkout is within a $GOPATH.
Although the go.mod versions match the glide.yaml ones, the diff
attached is large because Go Modules do not vendor `_test.go` files,
whereas Glide does.
[1]: https://golang.org/doc/go1.11#modules
[2]: `GOCACHE=on` will be deprecated in Go 1.12, so this change makes
sense for that reason, too.
Co-authored-by: brian m. carlson <bk2204@github.com>
New section (Branching strategy). This could be filled out a bit but I
don't know enough about your workflow to write it up with any more detail.
Explicitly mention master in the PR section.
