Skip to content

Commit 4b7c95a

Browse files
apauleyapauley
authored
Merge pull request #43 from apauley/contributing
Add a contributor's agreement
2 parents ef9d3e3 + c7aacd6 commit 4b7c95a

File tree

2 files changed

+237
-64
lines changed

2 files changed

+237
-64
lines changed

‎CONTRIBUTING.org

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
#+STARTUP: showall
2+
3+
* Hledger Flow Contributor Guidelines
4+
:PROPERTIES:
5+
:CUSTOM_ID: hledger-flow-contributor-guidelines
6+
:END:
7+
8+
Please read the [[#hledger-flow-contributor-agreement][Contributor Agreement]] before continuing below.
9+
By submitting a contribution it means that you agree to the terms in the
10+
contributor's agreement.
11+
12+
* List of Contributors
13+
:PROPERTIES:
14+
:CUSTOM_ID: list-of-contributors
15+
:END:
16+
17+
The complete list of contributors can be seen in the git logs or
18+
[[https://github.com/apauley/hledger-flow/graphs/contributors][on GitHub]].
19+
20+
If you have made a contribution, please consider adding your name (or github
21+
username) to the list below, and include it in a new or existing pull request.
22+
23+
Hledger Flow is brought to you by:
24+
- [[https://github.com/apauley][Andreas Pauley]]
25+
26+
* Contributing
27+
:PROPERTIES:
28+
:CUSTOM_ID: contributing
29+
:END:
30+
31+
To begin contributing, please follow these steps:
32+
33+
1. [[#get-the-project][Get the Project]]
34+
2. [[#build-the-project][Build the Project]]
35+
3. [[#find-an-issue][Find an Issue]]
36+
4. [[#create-a-pull-request][Create a Pull Request]]
37+
5. [[#get-your-pull-request-merged][Get Your Pull Request Merged]]
38+
39+
** Getting Started
40+
:PROPERTIES:
41+
:CUSTOM_ID: getting-started
42+
:END:
43+
44+
*** Get The Project
45+
:PROPERTIES:
46+
:CUSTOM_ID: get-the-project
47+
:END:
48+
49+
If you don't already have one, sign up for a free
50+
[[https://github.com/join][Github Account]].
51+
52+
After you [[https://github.com/login][log into]] Github using your
53+
account, go to the [[https://github.com/apauley/hledger-flow][Hledger Flow Project Page]], and click on [[https://github.com/apauley/hledger-flow/fork][Fork]] to fork the
54+
Hledger Flow repository into your own account.
55+
56+
Once you have forked the repository, you can now clone your forked
57+
repository to your own machine, so you have a complete copy of the
58+
project and can begin safely making your modifications.
59+
60+
To clone your forked repository, first make sure you have installed
61+
[[https://git-scm.com/downloads][Git]], the version control system used
62+
by Github. Then open a Terminal and type the following commands:
63+
64+
#+BEGIN_SRC sh
65+
mkdir hledger-flow
66+
cd hledger-flow
67+
git clone [email protected]:apauley/hledger-flow.git .
68+
#+END_SRC
69+
70+
This repository has some submodules included, mostly related to the
71+
examples in the documentation.
72+
73+
You need to initialise and update the submodules:
74+
75+
#+BEGIN_SRC sh
76+
git submodule init
77+
git submodule update
78+
#+END_SRC
79+
80+
*** Build the Project
81+
:PROPERTIES:
82+
:CUSTOM_ID: build-the-project
83+
:END:
84+
85+
You need a recent version of [[https://docs.haskellstack.org/en/stable/README/][stack]] installed.
86+
87+
Then run:
88+
89+
#+NAME: stack-build
90+
#+BEGIN_SRC sh
91+
stack build --pedantic
92+
stack test
93+
stack install
94+
#+END_SRC
95+
96+
Which should end with this:
97+
98+
#+BEGIN_SRC org
99+
Copied executables to ~/.local/bin:
100+
- hledger-flow
101+
#+END_SRC
102+
103+
Ensure that =${HOME}/.local/bin= is in your =PATH=.
104+
105+
Usually this means adding this to your =~/.bashrc=:
106+
107+
#+BEGIN_SRC sh
108+
PATH="${HOME}/.local/bin:${PATH}"
109+
#+END_SRC
110+
111+
**** Building with older Haskell Versions
112+
:PROPERTIES:
113+
:CUSTOM_ID: building-with-older-haskell-versions
114+
:END:
115+
116+
To build using an older version of GHC and related dependencies, point
117+
stack to one of the other yaml files:
118+
119+
#+NAME: stack-build-versions
120+
#+BEGIN_SRC sh
121+
stack test --stack-yaml stack-8.4.4.yaml
122+
stack test --stack-yaml stack-8.2.2.yaml
123+
#+END_SRC
124+
125+
*** Find an Issue
126+
:PROPERTIES:
127+
:CUSTOM_ID: find-an-issue
128+
:END:
129+
130+
You may have your own idea about what contributions to make to Hledger
131+
Flow, which is great! If you want to make sure the Hledger Flow
132+
contributors are open to your idea, you can
133+
[[https://github.com/apauley/hledger-flow/issues/new][open an issue]]
134+
first on the Hledger Flow project site.
135+
136+
Otherwise, if you have no ideas about what to contribute, you can find a
137+
list of issues on the project's [[https://github.com/apauley/hledger-flow/issues][issue tracker]].
138+
139+
Issues are tagged with various labels, such as =good first issue= or
140+
=help wanted=, which can help you find issues that are a fit for you.
141+
142+
If some issue is confusing or you think you might need help, then just
143+
post a comment on the issue asking for help.
144+
145+
Once you've decided on an issue and understand what is necessary to
146+
complete the issue, then it's a good idea to post a comment on the issue
147+
saying that you intend to work on it. Otherwise, someone else might work
148+
on it too!
149+
150+
*** Create a Pull Request
151+
:PROPERTIES:
152+
:CUSTOM_ID: create-a-pull-request
153+
:END:
154+
155+
To create a pull request, first push all your changes to your fork of
156+
the project repository:
157+
158+
#+BEGIN_SRC sh
159+
git push
160+
#+END_SRC
161+
162+
Next, [[https://github.com/apauley/hledger-flow/compare][open a new pull request]] on Github, and select /Compare Across Forks/.
163+
On the right hand side, choose your own fork of the Hledger Flow repository,
164+
in which you've been making your contribution.
165+
166+
Provide a description for the pull request, which details the issue it
167+
is fixing, and has other information that may be helpful to developers
168+
reviewing the pull request.
169+
170+
Finally, click /Create Pull Request/!
171+
172+
*** Get Your Pull Request Merged
173+
:PROPERTIES:
174+
:CUSTOM_ID: get-your-pull-request-merged
175+
:END:
176+
177+
Once you have a pull request open, it's still your job to get it merged!
178+
To get it merged, a core contributor has to approve the code.
179+
180+
Code reviews can sometimes take a few days, because open source projects
181+
are largely done outside of work, in people's leisure time. Be patient,
182+
but don't wait forever. If you haven't gotten a review within a few
183+
days, then consider gently reminding people that you need a review.
184+
185+
Once you receive a review, you will probably have to go back and make
186+
minor changes that improve your contribution and make it follow existing
187+
conventions in the code base. This is normal, even for experienced
188+
contributors, and the rigorous reviews help ensure that the quality of
189+
the code stays high.
190+
191+
After you make changes, you may need to remind reviewers to check out
192+
the code again. If they give a final approval, it means your code is
193+
ready for merge!
194+
195+
If you don't get a merge in a day after your review is successful, then
196+
please gently remind folks that your code is ready to be merged.
197+
198+
199+
* Hledger Flow Contributor Agreement
200+
:PROPERTIES:
201+
:CUSTOM_ID: hledger-flow-contributor-agreement
202+
:END:
203+
204+
Thank you for your interest in contributing to the Hledger Flow open
205+
source project.
206+
207+
This is the official contributor agreement for the Hledger Flow project.
208+
209+
The purpose of this agreement is to ensure:
210+
1. that there is a clear legal status and audit trail for the project
211+
2. that you get proper credit for your work
212+
3. that we are able to remain license-compatible with related software by
213+
updating to newer versions of our license when appropriate (eg maintaining
214+
compatibility with [[https://hledger.org/][hledger]])
215+
216+
By submitting a contribution you declare that all of your contributions to
217+
hledger-flow:
218+
- are free of patent violations or copyright violations, to the best of your knowledge
219+
- are released under the hledger-flow project's license
220+
- are granted legal ownership to both yourself and the project leaders of hledger-flow
221+
- may be relicensed in future at the discretion of the project leader
222+
223+
This contributor agreement describes the terms and conditions under which you
224+
may submit a contribution to us. By submitting a contribution to us, you accept
225+
the terms and conditions in the agreement. If you do not accept the terms and
226+
conditions in the agreement, you must not submit any contribution to us.
227+
228+
Although it is not required, we encourage you to add your name to the
229+
[[#list-of-contributors][list of contributors]] if you have made a contribution to the project.

‎README.org

Lines changed: 8 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ The easiest way to get it running is to download [[https://github.com/apauley/hl
4747
for your OS, and copy the =hledger-flow= executable to a directory in your PATH.
4848
Then just run it and see what it tells you to do.
4949

50-
You can also compile it yourself by following the [[#build-instructions][build instructions]].
50+
You can also compile it yourself by following the [[https://github.com/apauley/hledger-flow/blob/master/CONTRIBUTING.org#build-the-project][build instructions]].
5151

5252
* Overview of the Basic Workflow
5353
:PROPERTIES:
@@ -131,65 +131,6 @@ generated by the step-by-step instructions here:
131131

132132
[[https://github.com/apauley/hledger-flow-example][https://github.com/apauley/hledger-flow-example]]
133133

134-
* After Cloning This Repository
135-
:PROPERTIES:
136-
:CUSTOM_ID: after-cloning-this-repository
137-
:END:
138-
139-
This repository has some submodules included, mostly related to the
140-
examples in the documentation.
141-
142-
You need to initialise and update the submodules:
143-
144-
#+BEGIN_SRC sh
145-
git submodule init
146-
git submodule update
147-
#+END_SRC
148-
149-
* Build Instructions
150-
:PROPERTIES:
151-
:CUSTOM_ID: build-instructions
152-
:END:
153-
154-
You need a recent version of [[https://docs.haskellstack.org/en/stable/README/][stack]] installed.
155-
156-
Then run:
157-
158-
#+NAME: stack-build
159-
#+BEGIN_SRC sh :results none :exports both
160-
stack test
161-
stack install
162-
#+END_SRC
163-
164-
Which should end with this:
165-
166-
#+BEGIN_SRC org
167-
Copied executables to ~/.local/bin:
168-
- hledger-flow
169-
#+END_SRC
170-
171-
Ensure that =${HOME}/.local/bin= is in your =PATH=.
172-
173-
Usually this means adding this to your =~/.bashrc=:
174-
175-
#+BEGIN_SRC sh
176-
PATH="${HOME}/.local/bin:${PATH}"
177-
#+END_SRC
178-
179-
** Building with older Haskell Versions
180-
:PROPERTIES:
181-
:CUSTOM_ID: building-with-older-haskell-versions
182-
:END:
183-
184-
To build using an older version of GHC and related dependencies, point
185-
stack to one of the other yaml files:
186-
187-
#+NAME: stack-build-versions
188-
#+BEGIN_SRC sh :results none :exports both
189-
stack test --stack-yaml stack-8.4.4.yaml
190-
stack test --stack-yaml stack-8.2.2.yaml
191-
#+END_SRC
192-
193134
* Feature Reference
194135
:PROPERTIES:
195136
:CUSTOM_ID: feature-reference
@@ -658,10 +599,13 @@ also resonated with me:
658599
the way I am doing things, with as little effort as possible and
659600
without fear of irrevocably breaking things.
660601

661-
I've given [[https://pauley.org.za/functional-finance-hledger/][a talk]]
662-
at
663-
[[https://www.meetup.com/lambda-luminaries/events/qklkvpyxmbnb/][Lambda
664-
Luminaries Johannesburg]] featuring hledger and hledger-flow.
602+
I've given [[https://pauley.org.za/functional-finance-hledger/][a talk]] at
603+
[[https://www.meetup.com/lambda-luminaries/events/qklkvpyxmbnb/][Lambda Luminaries Johannesburg]]
604+
featuring hledger and hledger-flow.
605+
606+
* Contributing to Hledger Flow
607+
608+
Have a look at the [[file:CONTRIBUTING.org][contribution guidelines]].
665609

666610
* FAQ
667611
:PROPERTIES:

0 commit comments

Comments
 (0)