Skip to content

Commit 45289d7

Browse files
BillWagnerBillWagner
committed
update for first draft.
1 parent fb65bab commit 45289d7

2 files changed

Lines changed: 181 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,28 @@
11
# htbox.github.io
2-
The source for our Github.io site.
2+
This site provides the collection of our current policies on the Humanitarian Toolbox.
3+
In most cases, consider the guidance here as our current "default answer" to many
4+
important questios.
5+
6+
If you are working on a project, and you have a different recommendation, we will
7+
consider that request for a single single project. IF it works well in that project,
8+
we wwill consdier making it the default answer on new projects. We'll also consider
9+
adding that new policy to existing projects, in those cases where the benefits
10+
justify the work.
11+
12+
The site is built using Jekyll, so that we can easily support markdown
13+
formatted pages. Here are some important resources to get started:
14+
15+
This Gihub guide to creating pages with the automated generator shows the basics:
16+
https://help.github.com/articles/creating-pages-with-the-automatic-generator/
17+
18+
This article explains how Github uses Jekyll to generate the site:
19+
https://help.github.com/articles/using-jekyll-with-pages/
20+
21+
For those using Windows, this guide explains how to install and use Jekyll
22+
on Windows:
23+
http://jekyll-windows.juthilo.com/
24+
25+
If yuou have a procedure or a tool you'd like us to adopt, please send us a PR.
26+
This repository, like all of the HTbox projects, is open source, and
27+
we welconme your thoughts.
28+

‎_posts/2015-11-14-welcome-to-jekyll.markdown‎

Lines changed: 154 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,162 @@
11
---
22
layout: post
3-
title: "Welcome to Jekyll!"
4-
date: 2015-11-14 16:19:02 -0500
5-
categories: jekyll update
3+
title: "Contributing to HTBox projects"
4+
date: 2015-11-15 16:19:02 -0500
5+
categories: general contributing
66
---
7-
You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.
7+
Introduction
8+
All of our projects are Open Source, and released under the MIT license. Before you do anything,
9+
ensure that working on our projects does not conflict with any of your employee agreements.
810

9-
To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.
11+
We manage project workflow using a form of 'volunteer scrum' process. It's essentially scrum,
12+
but because we know everyone is a volunteer, we expect large flucuations in velocity. We
13+
also know that our volunteers have other committments, and may need to pull away from an
14+
assigned task before it's completed. Later
1015

11-
Jekyll also offers powerful support for code snippets:
16+
The remainder of this document explains how our projects are organized, how to assign
17+
yourself work, and how to sumbit that work for review. We'll also explain how to submit ideas
18+
for work that you want to do to enhnce our projects.
1219

13-
{% highlight ruby %}
14-
def print_hi(name)
15-
puts "Hi, #{name}"
16-
end
17-
print_hi('Tom')
18-
#=> prints 'Hi, Tom' to STDOUT.
19-
{% endhighlight %}
20+
Finding A Task
2021

21-
Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk].
22+
TL;DR version:
23+
24+
Look at the issues page for a project, select the Milestones tabl, and select the current
25+
milestone. Those are the items for the current sprint. If this is your first time helping us,
26+
look for issues tagged with the 'JumpIn' label. When you find one you like, write a comment saying
27+
"I'll work on this". One of the team will reach out to you, and see if you have any questions.
28+
29+
More details:
30+
31+
We use Github issues to manage work. This could be proposed features, tasks under a feature, bugs,
32+
and suggestions. We manage the backlog by using Milestones. Every project has a current milestone, and a
33+
backlog milestone. Issues assigned to the current milestone represent priority items in the current
34+
sprint. Issues assigned to the backlog milestone have been triaged and accepted, but have not been assigned any
35+
specific milestone.
36+
37+
Some projects have other upcoming milestones, based on customer needs, upcoming pilots, or upcoming
38+
releases.
39+
40+
In addition, we label issues to provide some additional guidance. Withing a milestone, we will use the 'P1',
41+
'P2' and 'P3' milestones to mark the priority of a task or feature. (P1 is the highest, P3 is the lowest.)
42+
In addition, we use the 'JumpIn' label (which is always green on our projects) to denote issues that would
43+
be suitable for someone not yet familiar with the project. The 'JumpIn' issues may not always represent
44+
simple fixes, but they do represent work that does not require a deep knowlege of the code base, or a deep
45+
knowledge of the business workflow for a project.
46+
47+
Other labels are project-specific and will be documented for that project.
48+
49+
Tag yourself in a comment saying that you're working on an issue, and we'll start the converation.
50+
51+
You may notice that you can't assign yourself to work on an issue. That privilege is limited to the
52+
core team. Also, we can only assign issues to registered team members. If you enjoy
53+
working on our projects, we'll add you to the team, and we will assign tasks when you tag yourself.
54+
55+
Getting the Code
56+
57+
TL;DR version
58+
59+
Fork the repository. Clone your fork using your favorite Git client tool
60+
61+
Long version:
62+
63+
We use the Github Flow process on all our projects (link). That means you are not commiting your
64+
changes directly to our repositories. Instead, you will submit a Pull Request for one of the
65+
lead committers to pull your changes into our repository. That enables us to review your
66+
changes, and discuss them with you. We even use this process ourselves: other core team members
67+
review our changes and pull them into the repository.
68+
69+
The first step in this process is to get the code onto your machine, configured with a
70+
github repository where you can commit your changes. You do that by creating a fork of
71+
the project repository in your account. You (and only you) have write access to your fork.
72+
73+
Now, you can clone your fork onto your desktop. You'll commit your changes locally, and
74+
then push them to your fork on github.
75+
76+
Building the project
77+
78+
TL;DR version
79+
80+
It's likely a Visual Studio based .NET project. Load the appropriate .sln and buld.
81+
82+
Longer version:
83+
84+
Some of our projects have both web and mobile components. Those will have a master solution,
85+
that builds everything. They will also have a -web solution that only builds the web based
86+
application. They may also have a -mobile solution that builds only the mobile applications.
87+
88+
Load the appropriate solution, and build it.
89+
90+
All our projects have some unit tests. The amount of coverage varies with the origins
91+
of the projects. In all cases, we encourage contributors to help add to the unit test coverage.at whatever adfadf
92+
For those projects where we do have good coverage, we may even reject pull requests without
93+
the addition of new tests that exercise the code being developed.
94+
95+
Doing the work
96+
97+
TL;DR version
98+
99+
Work as you normally would, commit and push your changes at the cadence that works for you.
100+
Please make one Pull Request for one Issue, rather than fixing several issues in on PR. It's much
101+
easier for us to review and merge when a PR is focused on one issue.
102+
103+
Long Version:
104+
105+
There are a few steps here that can help us review your pull request and ensure a smooth process
106+
when we take your code. All the tips described here make it easier for us to merge your changes
107+
with changes being made by other developers.
108+
109+
On at least a daily basis, rebase the changes you are making on the master branch <link>. This
110+
ensures that when you have completed your work, it merges easily into the master branch.
111+
112+
We recommending rebasing instead of merging the master branch into your fork because thaA creates a
113+
cleaner pull request.
114+
115+
Consider squash commits. A squash commit combines several original commit actions into one commit.
116+
The result is a single commit that shows all your changes. This isn't necessary, but if you are
117+
comfortable doing it, please do.
118+
119+
Submitting a Pull Request
120+
121+
TL;DR;
122+
123+
When you're doing with an issue, submit a pull request and we'll take a look.
124+
125+
Long Version;
126+
127+
You don't have to wait until all your work is done in order to send us a pull request. If you want
128+
the core team to look at your code, but not accept the changes yet, open a pull request, and prefix the
129+
title with 'WIP'. That tells us to review the code, but that it is not done, and is not yet ready to merge.
130+
When you are finished, and the PR is ready to merge, simply remove 'WIP' from the PR tktle, and we'll
131+
give it a final look, and merge it.
132+
133+
When you submit a pull request, an automated build (using AppVeyor) will merge your changes onto
134+
a copy of the master repository, build that configuration, and run all automated tests.
135+
136+
If any of those steps fail, we will ask you to fix them before we accept the pull request. (We don't
137+
comment on this if you've labelled the PR 'WIP'.)
138+
139+
We ask you to resolve any merge conflicts because you know your code the best. This article <link>
140+
shows how to update your fork from master.
141+
142+
Ideally, you can rebase your changes on the lastest version of mster. Here's a quick video that
143+
shows how to do that.
144+
145+
Responding to Reviews
146+
147+
TL;DR;
148+
149+
If you update your code, and push to your fork, github automatically updates the PR. We'll see the
150+
changes. If you disagree with the review, please comment on the code, and tell us why your
151+
approach is better. We may or may not approve it, but we will listen.
152+
153+
Long Version
154+
155+
Reviews are especially important when you are making your first PR for us. It's a way to have
156+
a conversation about the code as you make it. We appreciate the volunteer contributions we receive, and
157+
we value your time. We'd rather help comment early then reject work.
158+
159+
We review PRs (even WIP PRs) once a day, and we will give actionable feedback. Please respond in the
160+
same tone we use. We want great projects, and we respect your time and contribution. The people reviewing
161+
code are also volunteers and expect to receive the same respect.
22162

23-
[jekyll-docs]: http://jekyllrb.com/docs/home
24-
[jekyll-gh]: https://github.com/jekyll/jekyll
25-
[jekyll-talk]: https://talk.jekyllrb.com/

0 commit comments

Comments
 (0)