search

go-jira / jira

simple jira command line client in Go
Apache License 2.0
2.68k stars 328 forks source link

Fix documentation. #431

Closed fazlizekiqi closed 3 years ago

fazlizekiqi commented 3 years ago

Was trying to go through the README file. I found it really difficult to install the tool properly following the instruction. I am using MAC for development and was trying to install the tool manually and also with the "go". Didn't succeed it.

oschrenk commented 3 years ago

I think you would need to elaborate on your problems to address specific issues. What didn't work? Did the download not work? Were there too many choices, maybe too few? Are you familiar with the terminal?

fazlizekiqi commented 3 years ago

The download part worked. I was trying just to run "jira" after the downloaded part. Was getting that "the command not found". Tried to go in the src and install it manually with go. No success.

Yes, I am familiar with the terminal.

Different scenarios on how I tried to install it, correct me if I did something wrong:

Scenario 1: GO111MODULE=on go get github.com/go-jira/jira/cmd/jira According to the doc. this will build it and install it, which from my perspective means that i can at least run the "jira" command after the installation.

Scenario 2: Navigated to the src itself manually: github.com/go-jira/jira/ and tried to run go install. No success here neither.

Scenario 3: I downloaded one of the pre-built binaries for go-jira. Tried to install it. No success.

I'm using Mac OS Catalina version 10.15.7.

fazlizekiqi commented 3 years ago

I think a better title for the issue would be to Simplify documentation and not fix it. I really liked the idea of the tool but i don't really want to spend too much time on installing/configuring etc...

I am not a GO developer though. Can be something related to that as well.

oschrenk commented 3 years ago

(I am not a maintainer of go-jira and not associated with the project)

If you have Homebrew installed, you can also use:

brew install go-jira

That installation will also put the binary into an accessible place, so that you can "just" do jira.

As for the other installation methods (and addressing your comments):

Download

You need to know your operating system and CPU architecture. In your case I am assuming that you have macOS on an Intel CPU (not a newer M1). that means you need to download jira-darwin-amd64.

# asumming you have wget installed
wget "https://github.com/go-jira/jira/releases/download/v1.0.27/jira-darwin-amd64"

# OR

# asumming you have curl installed
curl -O -J -L "https://github.com/go-jira/jira/releases/download/v1.0.27/jira-darwin-amd64"

Now that you have your binary, you need to make it executable

chmod u+x jira-darwin-amd64

Now you have an executable file. If you are in the same directory, you can

./jira-darwin-amd64

That ./ is needed to make the oeprating system acknowledge the working directory as part of the $PATH. You might want/need to read up on the meaning of $PATH.

Go

The documentation says

GO111MODULE=on go get github.com/go-jira/jira/cmd/jira

You did that, but I think you overlooked the sentence after the next

It should then be available in $GOPATH/bin/jira.

So your binary is ready, but it is left to the user where to put it. You can execute it by running $GOPATH/bin/jira

Now you are left again with moving that binary to a place in your $PATH (or add $GOPATH/bin/ to your $PATH

Thoughts

It is a single binary and requires few installation steps compared to other things.

It is up to the user to decide where to put the binary in their own system. I think it's a sensible choice to leave that to the user and/or packaging managers (like home-brew) to do the last step.

fazlizekiqi commented 3 years ago

Great. Thanks for the clarification.

Having this part as a part of go-jira docs would probably help others as well.