source: subversion/applications/editors/josm/plugins/mapillary/INSTALL.md @ 32840

Last change on this file since 32840 was 32285, checked in by floscher, 4 years ago

Update several tools to their latest version

These are:

  • Java now uses source compatibility of 1.8 instead of 1.7 for compiling
  • Gradle 2.14
  • PMD 5.4.2
  • JaCoCo? 0.7.7
File size: 5.6 KB
Line 
1If you don't want to tinker with the code, just [install JOSM](https://josm.openstreetmap.de/) and open the Settings dialog in JOSM, choose the Plugin tab, check "Mapillary" and you are ready to go.
2
3But if you want to explore the sourcecode and maybe even improve it, first of all a :thumbsup: for you, and here are the instructions on getting the source code and building it on your machine:
4
5## Setting up your local git-repo
6
7```shell
8git clone git@github.com:floscher/josm-mapillary-plugin.git
9cd josm-mapillary-plugin
10```
11
12## Building the plugin with Gradle
13
14This project uses the so-called Gradle wrapper. That means you have to install nothing on your machine in order
15to build the project. The wrapper consists of the two scripts `gradlew` (for UNIX-based systems like Mac and Linux)
16and `gradlew.bat` (for systems running Windows). The following examples shows the commands for Linux/Mac users,
17Windows users can simply replace `./gradlew` with `./gradlew.bat`.
18
19If you develop using the Eclipse IDE, run the following command before opening the project in Eclipse. This will download the dependencies and tells Eclipse about where these dependencies are located on your machine:
20```shell
21./gradlew eclipse
22```
23As Eclipse plugins we recommend [eclipse-pmd](http://marketplace.eclipse.org/content/eclipse-pmd) and [Anyedit tools](http://marketplace.eclipse.org/content/anyedit-tools).
24
25For just building the jar-file for the plugin, run
26```shell
27./gradlew jar
28```
29
30If you also want to run the unit tests, create a FindBugs report and a code coverage report, then the following command is for you:
31```shell
32./gradlew build
33```
34(look for the reports in the directory `build/reports` and for the packaged `Mapillary.jar` in the directory `build/libs`)
35
36And finally, you can execute the following to build the plugin from source, and run the latest JOSM with the Mapillary plugin already loaded.
37This works regardless if you have JOSM installed, or which version of it. Any already present JOSM-installation stays untouched by the following command.
38```shell
39./gradlew runJosm
40```
41
42For info about other available tasks you can run
43```shell
44./gradlew tasks
45```
46
47---
48
49If you don't have push-access to the SVN-server, you should now be ready to go.
50
51The following paragraphs only deal with transferring commits from the git-repository to the SVN-server and the other way around.
52
53---
54
55## Connecting the git-repo to the SVN-server (optional)
56
57This step is normally only relevant, if you either have push-access to the SVN-server and want to push your commits from the git-repo to the SVN-repo. Otherwise just skip it.
58
59First, you need to have [`git-svn`](https://git-scm.com/docs/git-svn) installed. E.g. on Ubuntu, just run `sudo apt install git-svn`. On Windows you probably already installed it together with `git`.
60
61Then run the following commands:
62```shell
63git svn init --prefix=svn/ http://svn.openstreetmap.org/applications/editors/josm/plugins/mapillary #You have to use http://, _not_ https://
64git config --local svn.authorsfile authors.txt
65mkdir .git/refs/remotes/svn
66git rev-parse master > .git/refs/remotes/svn/git-svn # creates a file containing the SHA1 of master-branch
67git svn fetch
68git reset --hard svn/git-svn # Make sure you have no uncommitted changes in your repo before doing this
69```
70
71## Making changes to the repo and committing back to SVN (if you have git-svn set up as described above)
72
73The following steps are for those with commit-privileges for the SVN repository containing the plugins for JOSM.
74All others can simply file pull requests against the master-branch on github.
75
76We recommend, that you start your development at the head of the master-branch in a separate branch (in this example
77it's called _‹foo›_, you can name it what you like, but best call it after the feature you are working on):
78```shell
79git checkout origin/master
80git branch ‹foo›
81```
82
83---
84
85Then commit your changes to this branch _‹foo›_ until you feel it's time for committing them back to SVN:
86```shell
87git commit
88```
89
90---
91
92If you want to push (or in SVN-terms _commit_) all of the commits that you made on the _‹foo›_-branch back to SVN, then you can skip this step.
93
94Otherwise execute the following line to preserve the other commits:
95```shell
96git branch tmp
97```
98This creates a new branch called _tmp_ which saves those commits for later, which are not rebased.
99
100---
101
102Then fetch the current state of the SVN-repository to avoid merge conflicts:
103```shell
104git svn fetch
105```
106
107---
108
109Now you should rebase onto the current state of the SVN-repository:
110```shell
111git rebase --interactive svn/git-svn
112```
113A text editor should open with all commits on the _‹foo›_-branch that are currently not in SVN. Delete all lines except
114the ones containing those commits you want to commit to SVN.
115
116Watch the command line. If it says, that merge conflicts have occured you'll first have to resolve these conflicts.
117For example with the following command:
118```shell
119git mergetool --tool=‹name_of_your_mergetool›
120```
121Possible mergetools include emerge, gvimdiff, kdiff3, meld, vimdiff and tortoisemerge.
122
123After merging you'll have to tell git that it should complete the rebasing:
124```shell
125git rebase --continue
126```
127
128If it still says that there are merge conflicts, go back to the `git mergetool`-command and repeat the steps from there on.
129
130---
131
132You have reached the final step, the following command will now interact with the SVN-server to commit your changes
133to the SVN-repository:
134```shell
135git svn dcommit --interactive --username=‹your_svn_username›
136```
137This command will ask for your password and shows you the commit message of every git-commit before it
138applies it to the SVN-repo.
Note: See TracBrowser for help on using the repository browser.