Skip to content

Commit 16ae916

Browse files
tschaubtschaub
committed
Adding a readme with details for people that will be pushing to the central repository.
1 parent 3b3bc9f commit 16ae916

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎readme-dev.md

+173
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# OpenLayers 3
2+
3+
This document describes the process of cloning the central OpenLayers repository
4+
and making changes to it. It is really only relevant to developers who are
5+
currently core committers to the OpenLayers subversion repository. If you are
6+
interested in contributing to the future of OpenLayers, please clone the
7+
[central repository][1], make changes, and issue pull requests. We welcome your
8+
contributions and appreciate the help!
9+
10+
This document doesn't cover the git basics. The [help pages][2] on GitHub are a
11+
good place to start learning git.
12+
13+
There two type of changes developers will be making to the central OpenLayers
14+
repository. The first type will be commits that add features toward the
15+
OpenLayers v3 API or remove parts of the v2 API. The second type of change
16+
will be merges that come from the remote [OpenLayers subversion][3] repository.
17+
18+
[1]: https://github.com/openlayers/openlayers
19+
[2]: http://help.github.com/
20+
[3]: http://svn.openlayers.org/trunk/openlayers
21+
22+
23+
## Pushing Commits to the Central Repository
24+
25+
To make changes to the central git repository, you can fork it, add a reference
26+
(perhaps named "central" or "upstream") to the central repository, and push
27+
commits directly from your working copy. In addition, you can clone the central
28+
repository and push commits back to the "origin." The second process is
29+
described below.
30+
31+
First, clone the central repo:
32+
33+
git clone [email protected]:openlayers/openlayers.git ol3
34+
35+
Now you can make changes, commit often, and push commits:
36+
37+
cd ol3
38+
hack hack hack
39+
git commit -m "Making things awesome."
40+
hack hack hack
41+
git commit -m "Making things awesomer."
42+
git push origin master
43+
44+
45+
## Merging Changes from the Remote Subversion Repository
46+
47+
This section describes how to fetch changes from the OpenLayers subversion
48+
repository, merge those into the master git branch, and push them to the
49+
central repository on GitHub. The purpose for doing this is to bring changes
50+
from the 2.x line of development into the 3.x line of development. Not
51+
everybody will have to do this. And it should be done with caution. As the
52+
version 3 API changes from the v2 API, there will be increasing conflicts in the
53+
merges.
54+
55+
### Configuring your git repository to know about svn
56+
57+
First, check out (and change into) the 2.x branch if you haven't already. From
58+
within your ol3 git repository, run the following:
59+
60+
git checkout -b 2.x origin/2.x
61+
62+
The next thing you need to do to be able to merge in changes from subversion
63+
is to configure your working copy of the central git repository to know about
64+
the remote svn.
65+
66+
git svn init http://svn.openlayers.org/trunk/openlayers
67+
git config svn.authorsfile authors.txt
68+
69+
Note: The authors file links authors in subversion commits to GitHub users. The
70+
user names and emails in the authors file correspond to GitHub usernames and
71+
emails. Don't change this file unless you are correcting a GitHub user's
72+
information or adding a new author from the subversion log.
73+
74+
Finally, you need to configure your repo so it knows about the latest commit
75+
that the remote git-svn refers to. To do this, run the following:
76+
77+
git show origin/2.x | head -n 1 | sed 's/commit //' > .git/refs/remotes/git-svn
78+
79+
At this point, your local git repository should be configured to fetch changes
80+
from the remote OpenLayers subversion repository. Changes from this repository
81+
could be fetched (and applied to) any branch in your git repository, but by
82+
convention, we'll only apply changes from the SVN repository to the 2.x branch.
83+
Commits to the 2.x branch (which should only come from SVN) can be merged to
84+
your master branch (or any other) and then pushed to the central repository.
85+
86+
To confirm that your repository is correctly configured, run the following:
87+
88+
git svn info
89+
90+
You should see something like what you'd expect from `svn info` inside a
91+
working copy of a subversion repository. The first time you run it, you'll get
92+
a lot of extra output about rebuilding the revision map.
93+
94+
### Fetching changes from svn
95+
96+
As mentioned above, you can fetch changes into any of your git branches, but
97+
by convention, we only apply changes from the subversion repository to the 2.x
98+
branch.
99+
100+
If you haven't already, change into your 2.x branch (always run `git branch`
101+
before fetching or making changes to confirm what branch you are on) and pull
102+
the latest changes:
103+
104+
git checkout 2.x
105+
git pull origin 2.x
106+
107+
We expect all the changes in this branch to come from subversion - so you should
108+
never make commits (with `git commit`) directly to this branch. Instead, we
109+
always fetch changes from the remote subversion repository. Run the following
110+
to fetch changes and apply them as commits to your 2.x branch.
111+
112+
git svn rebase
113+
114+
At this point, you can push the commits from your local 2.x branch (the changes
115+
that came from svn) to the central git repo:
116+
117+
git push origin 2.x
118+
119+
### Merging changes from the 2.x branch
120+
121+
As with any other branch, changes from the 2.x branch can be merged into your
122+
master branch. As the OpenLayers v3 API diverges from the v2 API, these merges
123+
will likely come with a number of conflicts. Resolve these conflicts with care.
124+
125+
To merge changes (without conflict resolution), change to your master branch,
126+
pull the latest from the central repository, and merge changes from your 2.x
127+
branch.
128+
129+
git checkout master
130+
git pull origin master
131+
git merge 2.x
132+
133+
If all goes well, you can push the merged commits to the central repository:
134+
135+
git push origin master
136+
137+
138+
#### Notes for Posterity
139+
140+
If GitHub burns down and everybody with a clone quits their job and goes
141+
surfing, the git repository can be recreated with something like the following
142+
steps (the second one takes a long time to run, so I'm not going to
143+
reproduce it to confirm):
144+
145+
First, create an authors.txt file from an updated working copy of the svn repo:
146+
147+
#!/usr/bin/env bash
148+
authors=$(svn log -q | grep -e '^r' | awk 'BEGIN { FS = "|" } ; { print $2 }' | sort | uniq)
149+
for author in ${authors}; do
150+
echo "${author} = NAME <USER@DOMAIN>";
151+
done
152+
153+
Run this and save the output as authors.txt. Credits to [Josh Nichols][technicalpickles]
154+
for the script. Edit this authors file to correct any GitHub user names or
155+
email addresses.
156+
157+
Next, run the following (and substitute the path to the above mentioned
158+
authors.txt):
159+
160+
git svn clone -A path/to/authors.txt http://svn.layers.org/trunk/openlayers ol3
161+
cd ol3
162+
git remote add origin [email protected]:openlayers/openlayers.git
163+
git checkout -b 2.x git-svn
164+
git push -all origin
165+
cp path/to/authors.txt .
166+
git commit -am "Adding authors file."
167+
git push origin 2.x
168+
git checkout master
169+
git merge 2.x
170+
git push origin master
171+
172+
173+
[technicalpickles]:http://technicalpickles.com/posts/creating-a-svn-authorsfile-when-migrating-from-subversion-to-git/

0 commit comments

Comments
 (0)