Contributing to MapTool 1.4

Developer discussion regarding MapTool 1.4

Moderators: dorpond, trevor, Azhrei

Forum rules
Posting now open to all registered forum users.
Craig
Great Wyrm
Posts: 2107
Joined: Sun Jun 22, 2008 7:53 pm
Location: Melbourne, Australia

Contributing to MapTool 1.4

Post by Craig »

Here are the steps for obtaining and contributing to MapTool 1.4

MapTool source as of 1.4 is stored on GitHub. You don't need a GitHub account to contribute but it makes it easier for everyone if you do -- dont worry its free.
So this post will only contain instructions will assume you will create a GitHub account (https://github.com/) if for some reason any one has strenuous objections to creating a free account I will update the instructions to include other methods. These instructions are also IDE agnostic if someone wants to provide instructions for their favourite IDE we can add them, these instructions are a work in progress so I will be updating this post as people as for more details or clarifications on certain parts.

First create your GitHub account (https://github.com/)
Go to the MapTool repository https://github.com/RPTools/MapTool and click on the Fork button on the top right, this will fork a copy of MapTool in your account (it takes up no space, only changes you make to it take space (which will be tiny) so you never have to worry about them saying you are using too much space.

If you just want to make small changes like updating the internationalisation files and are ok using the GitHub editor then you can skip the installing the client step, otherwise...
Setup the GitHub client on your computer You can then go to your forked copy of MapTool and click on the Clone in Desktop button on the right and this should get the application installed above to grab the source.

Once you have made the changes that you want to make -- and tested them of course :) -- push them to your local repository and create a pull request https://help.github.com/articles/creati ... l-request/, this will send a notification with your changes. Please include a description or if there are a lot of changes a link to a post on the forums or something.

Building MapTool
Gradle is used to build MapTool 1.4, you do not need Gradle installed to perform the build as the repository has a small wrapper that will download it and install it in a subdirectory where the source is for you. This means that the first time you do a build you will need to be connected to the internet and the first build will take a while
as it downloads everything it needs.

To build
./gradlew build (or for Windows: .\gradlew build)

To create a distributable file
./gradlew clean release (or for Windows: \.gradlew clean release)
This will create a .zip file for use on all systems as well as a zipped .app for Mac OS X the build number will be based on the latest tag and latest commit.


GitHub Issue Log
There is an issue log on GitHub attached to the project located at https://github.com/RPTools/maptool/issues

The parser and rplib projects are not yet in GitHub but I plan to move them as soon as I get some free time.

User avatar
JamzTheMan
Great Wyrm
Posts: 1872
Joined: Mon May 10, 2010 12:59 pm
Location: Chicagoland
Contact:

Re: Contributing to MapTool 1.4

Post by JamzTheMan »

Thanks for the write up! Question on the Pull Requests....

Ok, I have MT 1.4 forked and now my own repository/version copied locally and make some changes. Lets say I modify MapToolFrame.java. Also, I have some changes in MapTool.java and ZoneView.java but those are not ready.

1. When I submit the pull request, I assume I can select which classes to submit.

2. Say, I submit the pull request, you like it but need to make some small changes (or incorporate some other changes) and then add it to the master. Is it easy to sync those changes back from the Master to my Fork without disturbing my other changes in my Fork?

3. In the past, when creating "Patches" in eclipse, code formatting could throw off the patch for comparisons. Is this an issue with Git? If I reformatted the code so before I modified it (eg {} are now on their own lines vs if(something){dothis();} will it just make it harder for you to compare or is that not an issue at all with Git?
-Jamz
____________________
Custom MapTool 1.4.x.x Fork: maptool.nerps.net
Custom TokenTool 2.0 Fork: tokentool.nerps.net
More information here: MapTool Nerps! Fork

Craig
Great Wyrm
Posts: 2107
Joined: Sun Jun 22, 2008 7:53 pm
Location: Melbourne, Australia

Re: Contributing to MapTool 1.4

Post by Craig »

JamzTheMan wrote:Thanks for the write up! Question on the Pull Requests....

Ok, I have MT 1.4 forked and now my own repository/version copied locally and make some changes. Lets say I modify MapToolFrame.java. Also, I have some changes in MapTool.java and ZoneView.java but those are not ready.

1. When I submit the pull request, I assume I can select which classes to submit.
When you issue a pull request its for everything in the branch so no you cant pick which classes :(
But unlike SVN branching works very well in git, and you can create your own branches easily (and quickly, as well as jump between them quickly) you don't need
someone on the original repo to create a branch for you etc, so you would just create a branch with the stuff to go up. Unless its a very small change you may even want
to create a branch to do your work, branches are really light weight so you can do them (as often as you like as long as you dont have so many you confuse yourself :) )
One thing to remember though is in git you merge at the commit level and a commit could have many files in it.
JamzTheMan wrote: 2. Say, I submit the pull request, you like it but need to make some small changes (or incorporate some other changes) and then add it to the master. Is it easy to sync those changes back from the Master to my Fork without disturbing my other changes in my Fork?
Git is better at dealing with merges than SVN for starters. Generally in that case I would apply your pull request, make the small changes and commit those. So when it comes time for you to sync its a change to the code you already have (not a change to the same parent it now has to work out the differences) so the merge should be seamless. Of course if you had edited the same line after sending pull request but before you get the changes then manual intervention may be required.
JamzTheMan wrote: 3. In the past, when creating "Patches" in eclipse, code formatting could throw off the patch for comparisons. Is this an issue with Git? If I reformatted the code so before I modified it (eg {} are now on their own lines vs if(something){dothis();} will it just make it harder for you to compare or is that not an issue at all with Git?
Its 7am here and I haven't slept yet so this question confuses me :) Um generally git has better merge than SVN and I don't think small formatting changes are going to cause issues for comparison sake. If you do do large reformats because the formatting is bad just give us a heads up to reduce the shock :) Uh I hope this answered the question.

User avatar
RPTroll
TheBard
Posts: 3159
Joined: Tue Mar 21, 2006 7:26 pm
Location: Austin, Tx
Contact:

Re: Contributing to MapTool 1.4

Post by RPTroll »

Thanks, Craig. This helps.

Here's a resource for learning GIT
http://git-scm.com/book/en/v2

and the video it came from
https://www.youtube.com/watch?v=-zvHQXnBO6c
ImageImage ImageImageImageImage
Support RPTools by shopping
Image
Image

User avatar
JamzTheMan
Great Wyrm
Posts: 1872
Joined: Mon May 10, 2010 12:59 pm
Location: Chicagoland
Contact:

Re: Contributing to MapTool 1.4

Post by JamzTheMan »

Yep, thanks! Not crazy about all the forks but it will only be crazy until we are all in sync.

Let me start with a small fork to test, maybe the map resize at it's mostly contained in new a new class IIRC. I'll post back here if I find any gotchas on the process.
-Jamz
____________________
Custom MapTool 1.4.x.x Fork: maptool.nerps.net
Custom TokenTool 2.0 Fork: tokentool.nerps.net
More information here: MapTool Nerps! Fork

User avatar
JamzTheMan
Great Wyrm
Posts: 1872
Joined: Mon May 10, 2010 12:59 pm
Location: Chicagoland
Contact:

Re: Contributing to MapTool 1.4

Post by JamzTheMan »

OK, I played with Git, eGit, GitHub, and Eclipse all night... :)

I got my projects on GitHub and was able to Fork MapTool and TokenTool. I found the following site really helpful: http://www.vogella.com/tutorials/Eclips ... ticle.html

Note#1: for fellow Eclipse (Luna) users, I found "Import Project from Git" to be a little buggy. If there was a Eclipse Project, it worked just fine (supplying a GitHub URL clone URL or local Repository), BUT if not and you selected "Wizard" selection to create a Project, it created a blank project under the workspace (vs pointing to the Git local repo). Selecting "General Project" instead worked great.

Note #2: It is suggested to create the repository outside your workspace for performance reasons. So your workspace really only holds your eclipse metadata and settings/plugin info and eGit doesn't scan all those extra files I guess.
-Jamz
____________________
Custom MapTool 1.4.x.x Fork: maptool.nerps.net
Custom TokenTool 2.0 Fork: tokentool.nerps.net
More information here: MapTool Nerps! Fork

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: Contributing to MapTool 1.4

Post by Jagged »

I am finding this all very timely as we a about to switch from Subversion to GitHub at work, so this is all legitimate investigation for me ;)

I was also playing with last night, and so far I have created the repository in my workspace. I used "Git for Windows" outside of Eclipse, to create a Maptool project in my workspace. Then used a Gradle plugin to import the project, which correctly recognised the two projects (Launcher and Maptool) within the parent Maptool folder.

Silly question: are we supposed to be using Java 8? I assumed we are, but got a build warning saying the source wanted 1.7.

User avatar
RPTroll
TheBard
Posts: 3159
Joined: Tue Mar 21, 2006 7:26 pm
Location: Austin, Tx
Contact:

Re: Contributing to MapTool 1.4

Post by RPTroll »

Was there anything special to get gradle working with eclipse?

My opinion is that we should standardize on Java 8 but what do I know. I'm a troll. Let me know if I need to spawn off a discussion topic about it.
ImageImage ImageImageImageImage
Support RPTools by shopping
Image
Image

User avatar
Jagged
Great Wyrm
Posts: 1306
Joined: Mon Sep 15, 2008 9:27 am
Location: Bristol, UK

Re: Contributing to MapTool 1.4

Post by Jagged »

RPTroll wrote:Was there anything special to get gradle working with eclipse?
Nope. Seemed to work without issue. When I have played with it some more, I will write up a "Clean Site Install" instructions for Eclipse.
RPTroll wrote: My opinion is that we should standardize on Java 8 but what do I know. I'm a troll. Let me know if I need to spawn off a discussion topic about it.
I don't think it needs a discussion, since 7 is end of life, we need to be on 8. I am currently working on the assumption, I haven't configured something correctly ;)

User avatar
JamzTheMan
Great Wyrm
Posts: 1872
Joined: Mon May 10, 2010 12:59 pm
Location: Chicagoland
Contact:

Re: Contributing to MapTool 1.4

Post by JamzTheMan »

Cool beans. And ya, I assume Java 1.8 but for now there shouldn't be an issue "supporting" 1.7.

I also used the Git for Windows but wasn't impressed, It seemed to lock up sometimes on republish. But doing the "Team Sharing" within Eclipse didn't seem work right either. It was easiest to Create the repo with Git for Windows and Publish it to GitHub, once that was in sync and Master was committed, I then created my Eclipse project via Import Git -> Local Repo.

I also initially tried to create a RPTools project folder in Git and using "Working Directories" under them for TokenTool, RPLib, and MapTool but RPLib was blank and couldn't figure out why so just gave up and created repo's under the root directory. Not sure what the advantage would be other than organization? (Maybe you can checkin/checkout multiple projects and update in one go I assume).


Haven't messed with Gradle yet. Excited to see your writeup! We started using RTC and Maven at work but I currently do not "code" anything at work except maybe a few weeks out of the year as that all goes offshore :( . So I don't get to play around much. I project manage at work so I have to get my coding fix here!
-Jamz
____________________
Custom MapTool 1.4.x.x Fork: maptool.nerps.net
Custom TokenTool 2.0 Fork: tokentool.nerps.net
More information here: MapTool Nerps! Fork

Craig
Great Wyrm
Posts: 2107
Joined: Sun Jun 22, 2008 7:53 pm
Location: Melbourne, Australia

Re: Contributing to MapTool 1.4

Post by Craig »

JamzTheMan wrote:Cool beans. And ya, I assume Java 1.8 but for now there shouldn't be an issue "supporting" 1.7.
My thoughts on the matter are 1.8 has been in GA for quite a while and there are several patches to it already so I can't see why we wont move to 1.8 soonish.
But for 1.4.0 (at the least) my goal is be compatible with the latest 1.3 so people can move straight from 1.3 to 1.4.0 and get any new features and bug fixes,
so for the first release I would want it to be compatible with 1.7 just incase there is some odd configuration out there that cant run 1.8 properly they still
have some of the extra features that have been around in custom builds.

Eventually though, I really dont want to have to try use the older JavaFX that comes with 1.7.

User avatar
JamzTheMan
Great Wyrm
Posts: 1872
Joined: Mon May 10, 2010 12:59 pm
Location: Chicagoland
Contact:

Re: Contributing to MapTool 1.4

Post by JamzTheMan »

I agree, we can push the audio stuff if needed to 1.x. I used JavaFX for it but it's not finished and might as well bundle it with other JavaFX and Java 1.8 changes. Although, I'd like to bundle a JRE with MT and it all kinda becomes a moot point.

In this day and age, we shouldn't require users to install Java separately and deal with Java updates. It's the number one killer in my group, every single one of em just says "meh, when it asks for update I click ok" then come to me and say "i don't know why this stopped working..." ug.

Edit:

FYI: To build in windows it's "gradlew.bat build" (at least from windows command prompt)

And I did get some warnings for TokenTool. We have some deprecation to fix eventually.
warnings

Code: Select all

D:\Development\git\tokentool>gradlew.bat build
Creating Release
:copyLibs
:compileJava
D:\Development\git\tokentool\src\main\java\net\rptools\tokentool\AppActions.java
:50: warning: PNGMetadata is internal proprietary API and may be removed in a fu
ture release
import com.sun.imageio.plugins.png.PNGMetadata;
                                  ^
D:\Development\git\tokentool\src\main\java\net\rptools\tokentool\AppActions.java
:152: warning: PNGMetadata is internal proprietary API and may be removed in a f
uture release
                                    PNGMetadata png = new PNGMetadata();
                                    ^
D:\Development\git\tokentool\src\main\java\net\rptools\tokentool\AppActions.java
:152: warning: PNGMetadata is internal proprietary API and may be removed in a f
uture release
                                    PNGMetadata png = new PNGMetadata();
                                                          ^
Note: D:\Development\git\tokentool\src\main\java\net\rptools\tokentool\ui\Contro
lPanel.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
3 warnings
:processResources
:classes
:jar
:assemble
:compileTestJava UP-TO-DATE
:processTestResources UP-TO-DATE
:testClasses UP-TO-DATE
:test UP-TO-DATE
:check UP-TO-DATE
:build

BUILD SUCCESSFUL

Total time: 14.109 secs

Edit 2:
When building MapTool in Eclipse/Windows, I was getting some errors. The plugin is slightly out of date, and can refer to: http://stackoverflow.com/questions/2628 ... el-of-type

To fix, I set my Gradle in Eclipse to use the gradle-2.3 I had installed manually. (I had set Gradle Enide but not Gradle distribution). Note, per the docs, this is better performance wise as Eclipse plugin now reuses the daemon on build if you are switching between command line/eclipse).

Preferences ->
Gradle ->
Gradle distribution - Folder D:\Progs\gradle\gradle-1.11
Gradle Enide->
Gradle home to use D:\Progs\gradle\gradle-1.11

Edit 3:
Can't figure this one out...If I do a "Gradle -> Refresh All" one of the things it does is refresh my Eclipse .project files adding
filteredResources
<filteredResources>
<filter>
<id>1426726551976</id>
<name></name>
<type>26</type>
<matcher>
<id>org.eclipse.ui.ide.orFilterMatcher</id>
<arguments>
<matcher>
<id>org.eclipse.ui.ide.multiFilter</id>
<arguments>1.0-projectRelativePath-equals-true-false-maptool</arguments>
</matcher>
<matcher>
<id>org.eclipse.ui.ide.multiFilter</id>
<arguments>1.0-projectRelativePath-equals-true-false-launcher</arguments>
</matcher>
</arguments>
</matcher>
</filter>
</filteredResources>
in which hide the maptool and launcher subproject folders and hence their source directories... I can run individual Gradle commands like clean, install, cleanEclipse, eclipse, etc and they don't touch the .project file. Aggravating.

Also not a fan of the source directories being buried 4 levels deep. Trying to find a way to bring/link those back to the top?

Edit 4:
Ok, starting to not like eGit when it comes to rebasing and merging back upstream. It's configured but not sure what it's doing wrong. I was commits behind, then commits ahead and behind, then just commits ahead...

Finally gave it, went to the power shell, found some new commands, FINALLY got the "This branch is even with RPTools:master". So, NOW I can work on a patch, and can test if the .gitattributes properly fixes the LR/CR issue hopefully.
-Jamz
____________________
Custom MapTool 1.4.x.x Fork: maptool.nerps.net
Custom TokenTool 2.0 Fork: tokentool.nerps.net
More information here: MapTool Nerps! Fork

User avatar
JamzTheMan
Great Wyrm
Posts: 1872
Joined: Mon May 10, 2010 12:59 pm
Location: Chicagoland
Contact:

Re: Contributing to MapTool 1.4

Post by JamzTheMan »

Craig, I created a branch and packaged up my first MapTool patch. You should see a pull request for it now.

Note: the line return attribute fix did seem to work just fine! BUT, you will probably see several "changes" due to code formatting. We may want to look into that further. I did see some things that would normalize the java code. Let me know what you want to do on that end.

For this patch, you can search for "autoResize", most of the variables, functions, classes, etc have that in the name and will jump you to the core of the changes. You shouldn't see anything too shocking.

Feel free to create a test build so people can poke at it. It's pretty solid and tested but you never know and I suspect the UI may need some polish (coders make the worst UI's lol).

Oh, and Wolf probably wants to play with it... :wink:
-Jamz
____________________
Custom MapTool 1.4.x.x Fork: maptool.nerps.net
Custom TokenTool 2.0 Fork: tokentool.nerps.net
More information here: MapTool Nerps! Fork


User avatar
RPTroll
TheBard
Posts: 3159
Joined: Tue Mar 21, 2006 7:26 pm
Location: Austin, Tx
Contact:

Re: Contributing to MapTool 1.4

Post by RPTroll »

So are we ready for a Maptool 1.4b01 test build? huh? huh? are we? are we?
ImageImage ImageImageImageImage
Support RPTools by shopping
Image
Image

Post Reply

Return to “MapTool 1.4”