Improve contributor experience

[maxmeyer]

Preface

This extracts some commits from #66 to focus discussion on related things.

Reason for separate PR

BTW, I think we don't really need to add those additional scripts, especially since go command is already simple enough to use. For example, setup is just wrapper for go get and build is just wrapper for go build.

Changes introduced

• Add scripts
• Documentation for those scripts
• Migrate dependency handling to dep as it is stable and can handle that task well This failed and was removed in a later iteration
• Migrate logic from .travis.yml to scripts to make it usable for contributors as well
• Replace logic in Dockerfile with scripts

[maxmeyer]

@RadhiFadlillah
You're right about that the scripts are quite small, but I still think it makes sense to have them.

Personally I think,

• that using go get and the like is an "implementation detail" for (new) contributors
• that's a good thing to have a single place for build/test/setup logic
• this kind of abstraction reduces the risk that one forgets to change the documentation after adding more logic to the build/build/setup-step in .travis.yml and Dockerfile

Reasons for the proposal:
I'm involved in quite a few projects to fix things, to add new features, to fix documentation, to dockerize the project etc. In most cases it's cumbersome to get started. There's no documentation what is required to setup the project, what kind of tests need to be run and how I can build the project. That's why I like the proposal found in here https://githubengineering.com/scripts-to-rule-them-all/. Having a simple script is an easy entry point. Giving them clear names makes their use case obvious. Since Ive got the script I don't need to care which tool is used to bootstrap the project etc.

[maxmeyer]

@RadhiFadlillah Rebased to HEAD.

[peteretelej]

@maxmeyer sorry but I think using go get keeps with Go convention and IMHO a makefile + scripts would be an unnecessary overhead, since the app's build process is quite straightforward.

At the moment, these things seem straightforward;

• to do fetch source,update, build and install this is the only thing to run:
  go get -u github.com/RadhiFadlillah/shiori
• building binaries from source is simply go build
• testing is go test ./...
• to build the docker image docker build -t myname/shiori . ~ this may be better than what the build script does (since this is a custom build + can't be pushed to Radhi's docker acc) .
• to use the official docker container is docker run -P radhifadlillah/shiori

I'm involved in quite a few projects to fix things, to add new features, to fix documentation, to dockerize the project etc. In most cases it's cumbersome to get started. There's no documentation what is required to setup the project, what kind of tests need to be run and how I can build the project.

Not usu the case with go apps (like explained above), unless am not getting something. Maybe the documentation may need sprucing up to make the commands clear

[maxmeyer]

Hey @peteretelej

sorry but I think using go get keeps with Go convention and IMHO a makefile + scripts would be an unnecessary overhead, since the app's build process is quite straightforward.

I dont' want to change that for normal users - README. I like the idea to have a simple command to install an app.

to do fetch source,update, build and install this is the only thing to run:
go get -u github.com/RadhiFadlillah/shiori

That's true for users

building binaries from source is simply go build

Please, have a look at .travis.yml, for platform dependent builds gox is involved, so it's not just go build. That's not obvious for new contributors - at least not for me.

testing is go test ./...

Again, please have a look at .travis.yml. go vet is also involved, which is again not obvious for first timers.

to build the docker image docker build -t myname/shiori . ~ this may be better than what the build script does (since this is a custom build + can't be pushed to Radhi's docker acc) .

I'm not sure what you mean with can't be pushed to Radhi's docker acc. Of course @RadhiFadlillah can do docker push radhifadlillah/shiori after loging in.

Not usu the case with go apps (like explained above), unless am not getting something. Maybe the documentation may need sprucing up to make the commands clear

For the normal user tasks, this is clear. But today there's a lot of knowledge hidden within the .travis.yml-file.

I don't think it's neccessary to have scripts, but I would argue, that all knowledge to build/test the app should be obvious and either clearly documented or abstracted by a utility.

[peteretelej]

please ignore the .travis.yml file. gox is not part of the build process, the build process is simply go build, gox is used to automate the build for various platform binaries (in this case travis uses it for deploying the releases to github). go vet is usually included as part of most editor's linters (hence you really won't be using it explicitly, if you do gometalinter would be the way to go)

all knowledge to build/test the app should be obvious and either clearly documented or abstracted by a utility.

True.