You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Hi. We are thrilled that you are interested in Contributing to this project. Good contributions keep this project great! This document outlines how you should contribute hopefully that would make it easier to get your contributions accepted.
9
5
10
6
### Getting started
11
-
-clone the repository
12
-
-read godocs and guidelines for writing gocode
7
+
-read godocs and guidelines for writing go code
8
+
-set up the project
13
9
- run the project and get to know it
14
-
-`work on` an issue in a feature branch, then `deliver` your branch and make it available for review.
In general, this project runs according to the workflow described in Praqma's blogpost [A pragmatic workflow](http://www.praqma.com/stories/a-pragmatic-workflow/). We call this workflow and branching model "The Phlow".
15
+
In general, this project runs according to the workflow described in Praqmas blogpost [git-phlow](https://www.praqma.com/stories/git-phlow/).
18
16
19
17
The super short summary of this workflow is:
20
18
- create a feature branch for your issue. E.g. feature/42-some-issue-title
@@ -38,38 +36,24 @@ When you have the project up and running, check our [github issues](https://gith
38
36
39
37
Even though this is still a small fledgeling project, we want to make it easily accessibly to contribute, whether you are an experienced go-lang and git expert or not.
40
38
41
-
Some issues are labelled with `Difficulty - easy`. This label indicates that we believe the issue is of a nature where people unfamiliar with the project, unexperienced in go-lang or programming in general or just new to contributing to open source repositories, can easily get started. We might not be there quite yet, be will will try to go that extra mile in providing better descriptions and clear scopes for these issues.
39
+
Some issues are labelled with `help wanted` or `good first issue`. This label indicates that we believe the issue is of a nature where people unfamiliar with the project, unexperienced in golang or programming in general or just new to contributing to open source repositories, can easily get started. We might not be there quite yet, be will will try to go that extra mile in providing better descriptions and clear scopes for these issues.
42
40
43
-
Please note: If you do consider yourself the target audience for these *Easy* issues, be awesome and pick some of the slightly harder tasks. It is tempting to quickly grab and complete the easy ones, but this quickly leaves no obvious tasks for newcomers to tackle.
41
+
Please note: If you do not consider yourself the target audience for these *Easy* issues, be awesome and pick some of the slightly harder tasks. It is tempting to quickly grab and complete the easy ones, but this quickly leaves no obvious tasks for newcomers to tackle.
44
42
45
43
Another way that you can help, if you are more experienced in specific areas, is to help **groom** the *Easy* tasks, to make them even easier. Suggest how a given problem might be solved, where in the code base a given bug might probably be found, or mention in the issue that you are willing to provide specific guidance. Any help in grooming the larger issues and splitting them up into beginner friendly chunks is also greatly appreciated.
46
44
47
45
Most of the people so far involved with the project are all pretty new to Go. If you know little of git or extensions, but are well versed in Go, please keep your eyes open on ongoing issues and offer help where you can. Contributions to an open source project are absolutely not only about getting a code contribution merged. Helping others contribute, writing documentation, grooming tasks, triaging reported bugs and so on are all very valuable contributions and will be greatly appreciated.
48
46
47
+
If you haven't written go code before, we recommend to take the [go tour](https://tour.golang.org/welcome/1); it will provide great insight in the go programming language. As a reference we recommend [gobyexample](https://gobyexample.com/)
49
48
50
-
To understand the-phlow read praqmas great story about what is is and how it works.
51
-
it will you understand what git-phlow is and what we are building
If you haven't written go code before, I recommend to take the [go tour](https://tour.golang.org/welcome/1); it will provide great insight in the go programming language. As a reference i recommend [gobyexample](https://gobyexample.com/)
55
-
56
-
**Project dependencies**
49
+
### Configure the shell for git-phlow
57
50
58
-
The project uses other frameworks and libraries, it is recommend to read about them to get an understanding of what they do, provide and how to use them.
51
+
Download the latest release for your platform and install it. Follow the [installation guide](/docs/installation.md)
59
52
60
-
[Cobra](https://github.com/spf13/cobra) is both a library and a CLI, and is the library we use in our CLI. Cobra itself has a CLI, which sets up boiler plate cmd's in the cmd folder. use it by typing `cobra add <name of cmd>`
61
-
62
-
[GoConvey](https://github.com/smartystreets/goconvey) is the testing framework we use for unit tests, it provides and BDD expressions in your tests, like the nodejs [mocha](https://mochajs.org/) test framework
63
-
64
-
### Get you shell configured for the-phlow
65
-
66
-
**Get the latest release**
67
-
Download the latest release for your platform and install it. You can follow the guidelines on the README page.
68
-
69
-
### Get the project set up on your machine
53
+
### Setting up the project
70
54
71
55
Go to [get golang](https://golang.org/doc/install) and get the latest version and install it on your machine.
72
-
it should be available on `brew` aswell.
56
+
it should be available on `brew` aswell, running `brew install go`
73
57
74
58
Next you need to setup your shell for go development, this is also documented on go' website. Export GOPATH and GOBIN, in your shell config,
75
59
eg. `zshrc`if you are using zsh.
@@ -80,32 +64,30 @@ export GOBIN=$GOPATH/bin
80
64
export PATH=$PATH:$GOBIN
81
65
```
82
66
83
-
Next up is getting our project. Use go's own tool `go get` or clone the repository into your GOPATH under, src/github.com/praqma/
67
+
Next up is getting our project. Clone the repository into your GOPATH under, src/github.com/praqma/
84
68
```bash
85
-
go get -v github.com/praqma/git-phlow #downloads the project to you gopath
86
-
87
-
#go to the project folder /src/github.com/praqma/git-phlow and enter following command
Go has a great toolset for running rests. As a standard go runs the test from the current directory you are in, if you want to run tests from subdirectories or just all tests, run:
93
76
94
-
`go test -v -p 1 ./... # -p 1 makes sure to run test in one thread. Important for the project test fixture`
77
+
`ginkgo -r -v --trace`
95
78
96
79
For specific directories, run:
97
80
98
-
`go test /folder`
81
+
`ginkgo` inside a folder
99
82
100
83
101
84
### Building
102
-
To build binaries go also comes with a pre installed tool, `go build`
103
85
104
86
To build and drop a binary in the root directory of your project, run:
105
87
106
88
`go build #Build and adds a binary to the root of the project`
107
89
108
-
To install the binary in the bin folder in your GOPATH, you can run a different command.
90
+
To install the binary in the `bin` folder in your GOPATH, you can run a different command.
git-phlow (pronounced _"git flow"_), is a CLI extension for git, which provides an extra set of commands to easily use our pragmatic workflow called **the phlow**. It provides a branching model which makes collaboration easy. It also provides automatic issue tracking using [GitHub](https://github.com) issues with [Waffle](https://waffle.io/). The branching model uses branches prefixed with `ready` (can be configured) to mark delivered tasks to the remote repository from where automation services can pick up and integrate the changes into the stable branch.
13
-
14
-
Read about the pragmatic workflow, **the phlow**[here](http://www.praqma.com/stories/a-pragmatic-workflow/).
11
+
Git-phlow (pronounced _"git flow"_), is a CLI extension for git, which provides an extra set of commands to easily use our pragmatic workflow by the same name, **g´Git phlow**. It provides a branching model which makes collaboration easy. It also provides automatic issue tracking using [GitHub](https://github.com) issues or Jira.
15
12
16
13
git-phlows core features include:
17
14
18
15
-*works with GitHub and waffle*: git-phlow assigns labels to move around user stories on waffle boards, and managing your github issues.
19
16
20
-
-*branches based on issues*: `workon` creates a branch from a GitHub issues and moves it to "wip"
21
-
22
-
-*issue tracking*: having all your user stories as waffle cards or GitHub issues, git-phlow will mark them appropriately to their status.
23
-
24
-
-*build for pretest integration*: `deliver` pushes your branch to GitHub, ready for your pipeline to pull, integrate, test and merge back in.
25
-
26
-
## Using the phlow (workflow)
27
-
To get started using the-phlow, read [praqmas](http://www.praqma.com/stories/a-pragmatic-workflow/) article about how the phlow works, and how to configure Waffle for your projects.
28
-
A few things nees to be configured before hand:
29
-
30
-
- Activate __issues__ on the designated GitHub repository
31
-
- Create the __labels__ used by the phlow. Read the article above to find them
32
-
- Download and install _git-phlow_ using _brew_ or _wget_
33
-
- Start creating tasks in GitHub issues
34
-
35
-
Read the official documentation [here](/docs/README.md)
36
-
37
-
## Installing git-phlow (tool)
38
-
### Mac
39
-
If you have homebrew installed, you can tap our official repository.
40
-
41
-
```shell
42
-
# Tap our repository
43
-
brew tap praqma/praqma-tap
44
-
45
-
# Install git-phlow
46
-
brew install git-phlow
47
-
48
-
# Upgrade to a new version
49
-
brew upgrade git-phlow
50
-
```
51
-
52
-
### Linux
53
-
Install git-phlow by running the following commands. Remember to use the latest release.
54
-
55
-
```shell
56
-
wget https://github.com/Praqma/git-phlow/releases/download/v3.8.2/git-phlow-3.8.2-linux-amd64.tar.gz && tar -xzf git-phlow-3.8.2-linux-amd64.tar.gz && mv git-phlow /usr/local/bin
57
-
```
58
-
59
-
### Windows
60
-
61
-
On Windows you have the option of using either using [scoop](http://scoop.sh/) or [Chocolatey](https://chocolatey.org/)
62
-
63
-
**Install using Scoop**
64
-
65
-
_First install Scoop if you don't have it and add our scoop-bucket_:
66
-
67
-
Open powershell and get the latest release of scoop
- Look at the issues by using `ghi` or going to GitHub or Waffle
141
-
- Find an issue to work on, and note its id e.g. `42`
142
-
- Go to the local git repository and type:
143
-
144
-
```git
145
-
git phlow workon 42
146
-
```
147
-
148
-
- This will create a branch: `42-some-issue-title`
149
-
- Make the changes and complete the task
150
-
- When done, add everything and commit with a single command:
151
-
152
-
```git
153
-
git phlow wrapup
154
-
```
155
-
156
-
- Now that the changes are ready, type:
157
-
158
-
```git
159
-
git phlow deliver
160
-
```
161
-
162
-
- It renames the local branch to: `delivered/42-some-issue-title`
163
-
- It pushes remote branch named: `ready/42-some-issue-title`
164
-
165
-
If the automation tools have been configured to listen for __ready/__ branches, they will pick up the branch and integrate them with the stable branch.
166
-
If you do not have an automation system, you can deliver the work to your default branch by doing a local deliver instead.
167
-
168
-
```git
169
-
git phlow deliver --local
170
-
```
171
-
172
-
- Changes branch to `master`
173
-
- Merges changes from `42-some-issue-title`
174
-
- Pushes changes to GitHub
23
+
## Getting started
24
+
To read the concepts behind git-phlow read [praqma's article](https://www.praqma.com/stories/git-phlow/) about the workflow.
25
+
Consult the [official documentation](/docs/README.md) for information on how to get started using git-phlow
175
26
176
27
### Automation systems
177
-
We use Travis CI, Concourse CI and Jenkins. They can all be configured to follow the phlow and listen for ready branches.
178
-
You can see the Concourse pipeline configured for this project [here](https://concourse.bosh.praqma.cloud/teams/main/pipelines/git-phlow)
28
+
We use Travis CI, Concourse CI and Jenkins. They can all be configured to follow git phlow. You can see the Concourse pipeline configured for Git-phlow [here](https://concourse.bosh.praqma.cloud/teams/main/pipelines/git-phlow)
179
29
180
30
### git-phlow on Windows
181
31
182
-
We recommend running git-phlow using _PowerShell_.
32
+
git-phlow works in _PowerShell_ on windows.
183
33
There are known issues with _cmd_ rendering formatted text incorrect, and _git bash_'s input being handled incorrectly.
184
34
185
-
## Project status
186
-
This is the official repository for the git-phlow extension. The project is currently under development and many additions are still to come. but version 0.1.5 is available and stable for both linux and Mac.
187
-
188
-
## Getting started
189
-
**Know the phlow, know go**
190
-
To understand the-phlow read praqmas great story about what is is and how it works. [read me, please!](http://www.praqma.com/stories/a-pragmatic-workflow/)
35
+
### Project status
36
+
This is the official repository for the git-phlow extension. The project is currently stable at version 3.8.2 for both windows, macOS and linux.
191
37
192
38
### Contribution
193
39
Contributions are welcome! Please read the [contribution guide](https://github.com/Praqma/git-phlow/blob/master/CONTRIBUTING.md)
[ Get more details at **codescene.io**.](https://codescene.io/projects/1345/jobs/latest-successful/results)
0 commit comments