Basic Developer Setup

From PCGen Wiki
Jump to: navigation, search

Initial Setup

Download eclipse or IntelliJ. This guide will assume you are using Eclipse Oxygen (2) (released Sep 2017) or newer.

Download Java 9. You MUST download a Java Development Kit (JDK) not a Java Runtime Environment (JRE). a JDK is required to be able to compile Java.

Go to github and set up an account if you don't have one already

Go to HipChat and set up an account and join the PCGen channel:

  • https://www.hipchat.com/gz9QBLp23
    • This is the first place to go for help if you are having trouble getting set up. You or someone can "page" @Tom Parker and I'll drop by when I can.

Repository Setup

We use git as a Version Control System. To use the git workflow, you will need to fork the primary PCGen code.

Getting Eclipse Set up (The Basics)

  • Start up eclipse. If it's the first time you've used Eclipse, click on the "Go to Workbench" picture (an arrow of some form).
  • Under the Window menu, go to preferences.
  • Open the twistie for "Java", select "Installed JREs". Ensure that the Java 9 JDK is selected. If it is not selected, select it. If it is not there, click the "Add" button and find it. On Windows, this will likely be in c:\Program Files\Java
  • Under the twistie for "Java" then select "Compiler" and then set the Compiler Compatibility Level to "1.8"
    • We are in process to moving to 1.9, but not all of the necessary updates are complete
  • Open the twistie for "Team", then select "Git". Ensure it has a "Default Repository Folder" you are okay with. (You will need to know this later)
  • Click "Apply and Close"

Opening the PCGen git repository:

  • Under the Window menu, select "Show View" and in the submenu, select "Other". Open the twistie for "Git" and then select "Git Repositories" and click "Open"
  • That view will likely appear in the lower left. Click the icon that is "Clone a Git Repository and add the clone to this view".
  • For the URI enter: https://github.com/<userid>/pcgen (replace <userid> with your github userid)
  • Ensure the host lists as "github.com"
  • Ensure the Repository Path is /<userid>/pcgen
  • Set the protocol to https
  • Enter your github userid and password as well
  • Click "Next>"
  • For branches, deselect all and then just select "master"
  • Click "Next>"
  • Leave the remote name as "origin" and ensure you DO NOT click on "Import all existing eclipse projects"
  • Click "Finish"

This will add a respository to the list called "pcgen".

  • Open the twistie and then right click on "remotes". Select "Create Remote"
  • For the name, enter "upstream".
  • Click "Configure fetch"
  • Click "OK"
  • Click "Change" to set the URI; for the URI enter: https://github.com/PCGen/pcgen
  • Ensure the host lists as "github.com"
  • Set the protocol to https
  • Ensure the Repository Path is /PCGen/pcgen
  • Enter your github userid and password as well
  • Click "Finish"
  • Ensure the Ref mappings are:
  • +refs/heads/*:refs/remotes/origin/*
    • If this is not present, click "add". If it's not correct, click it then click "modify".
    • The part before the : goes in "Remote Branch or Tag"
    • The part after the : goes in "Tracking branch:"
    • If necessary, click "OK"
  • Click "Save"

Import the Project

  • From the "File" menu, select "Import..."
  • Open the twistie for "Gradle" and then select "Existing Gradle Project"
  • Click "Next>" (and again if your system shows the welcome screen)
  • For the project root directory, click "Browse" and find the directory in which the git repository is located, and select the pcgen folder.
    • For Windows users, by default, the git folder is under C:\Users\<Windows userid>\git
  • Click "Next>"
  • Don't override anything on the Import Options
  • Click "Next>"
  • At Import Preview, click "Finish". This will import the project, and you should now see it in the "Package Explorer"

Set up the Project

  • Right click on the "pcgen" package and at the bottom select "Properties".
  • Open the "Java Code Style" twistie and select "Formatter"
  • On the right select "Enable Project Specific settings"
  • For the active profile, click "Import"
  • Browse into the git repository, then pcgen/code/standards/ and select "eclipse32_pcgen.xml"
  • When that is the active profile, click the "Apply and Close" button at the bottom.

TODO: *We need to get the organize imports set up here, but Eitan knows the formal list we adopted)

We do NOT push pull requests from our local master, that is a bad practice. We always operate from branches in our local repositories.

Create Branch

  • Down in "Git Repositories", open the twistie "pcgen" then "branches", then "Local" and then click on "master"
  • Right click and select "create branch"
  • Name the branch
  • Click the check box for configure push and pull
  • click "OK"

This will then check out the branch and the large black check mark will be on the branch.

In these next steps, you may have to enter a password and may have an option to cache the password. Since mine is cached, I can't specify how often this happens, but provide it as necessary.

Commit code

  • Make a sample change to a file (you can just open any file in the sources and change a comment)
  • Right click on the repository up in the package explorer, and select "Commit"
  • This will open the "Git Staging" Window.
  • Ensure the items you want are in the lower left. If they are in the upper left, you can click on them and select "add to index". If you have files you don't expect, please investigate what they are!
  • On the right side, add a commit message. Please make this useful as to what was done. It can be short/terse. If a JIRA tracker is involved, please include the tracker name as the START of the FIRST line.
  • Click "Commit"

Run the build

  • In general you should be testing before you push or submit a Pull Request - Please DO NOT rely solely on the automated tools to catch errors. We have unit tests for a reason :)
  • In the package explorer, find a file called "build.gradle"
  • Right click on that and select "Run As" and then "run configurations"
  • In the window that appears, click on "Gradle Project", then create a new run configuration (click the new icon). For the gradle tasks, include "clean build slowtest". These need to be on one line, with spaces separating them and NO R ETURN CARRIAGE at the end. Eclipse Oxygen is very sensitive about this, unfortunately.
  • You should not need to set anything else, just click "Run"
  • The tests should run and complete successfully.

Push code

  • Right click on the pcgen repository in the Package Explorer and select "Team" and then "Push to Upstream"
  • This pushes up to your repository on github.

Create a Pull Request

  • Go to github.com and ensure you are logged in.
  • Go to https://github.com/PCGen/pcgen
  • You are likely to have a yellowish banner near the top that is "review and create pull request" (or some similar text)
  • Click on that.
  • Review the name of the issue to ensure any JIRA issue is at the START of the title.
    • For your first PR, if you proceed through these steps, PLEASE INCLUDE "SAMPLE: DO NOT MERGE" if it is not intended as a real change.
  • Add any additional comments that can explain the purpose of the pull request are helpful. A code review will be performed.
  • Click "create pull request"

Travis

  • When a pull request is submitted, a few automatic jobs are kicked off. This includes Travis (which performs a build) as well as other validation of code quality.
  • While these are running, a yellow dot appears next to the PR on the pull requests page: https://github.com/PCGen/pcgen/pulls
  • If all are successful, that changes to a green check mark. If any fail, a red X appears. If the red X appears, please modify the code to fix the issue and do another push.

Review and Merge

  • All PRs are reviewed by more experienced code folks on the project.
  • We are checking for basic items as well as how well it will interact with existing systems.
    • Any PR with more than 10 commits will be rejected unless there is a good explanation for the complexity. It's best if it has one, but a second one to fix review issues is fine.
    • Please squash as necessary to keep the commit count to a minimum.
    • Please try to keep it one issue to a commit. Smaller commits are better since we are reviewing what they do.
    • Please do not submit any formatting PRs without first consulting with the team. In many cases, we have multiple side projects going on, and having to merge and rebase those around minor changes can be time consuming. We CAN find time to do that level of cleanup - it's good to do - but it needs to be properly scheduled so as to not waste time.
  • If the PR is accepted, it will be merged; if not, you will get comments on what to address in the PR.
    • In general, we try to "merge and rebase" since it keeps the commit history cleaner. You may occasionally be asked to rebase your code to bring it up to a newer level.

Updating

  • Once any merge has been made, you will want to grab the updated code.
  • Make sure you do NOT have any local changes - you should NOT have a black asterisk or a ">" sign next to the pcgen folder in the Package Explorer before proceeding.
  • Check out your "master" branch by double clicking on it in the "Git Repositories" or right clicking on it and selecting "Checkout"
  • right click on it and select "Configure Branch..."
  • In the window that appears, set the remote to "upstream"
  • Click "ok"
  • In the package explorer right click on the "pcgen" project, select "Team" and "Pull".
  • Right click on it and select "Configure Branch..."
  • In the window that appears, set the remote to "origin"
  • Click "ok"
  • In the package explorer right click on the "pcgen" project, select "Team" and "Push to Upstream".
  • This has now taken the changes from the team's master (upstream) to your master (origin). At that point, you can rebranch off the new (cleaner) master and do other work.


Social / Communication:

  • We tend to hang out on HipChat for the most part.
  • There is a developer list ( http://groups.yahoo.com/group/pcgen_developers/ ), but that's mostly for persistent things (votes or logs) at this point, most smaller questions end up on HipChat.


Participating in PCGen

  1. Play nice. Use common sense. We're all here because we enjoy it and want to participate in this project. Challenging ideas is ok (all of us will not always agree on a specific point), but don't attack people (no flames!)
  2. Make sure to run the unit tests and only create a Pull Request (PR) when they all pass. Having said that, I suspect we've all broken the code at least once, so *don't stress* about it if it happens. Just participate in fixing it or get help from someone who can (if you really have no idea what's broken).
  3. If you're changing LST Token syntax (from our data files) then you need to get permission from the Data monkeys. You will find them on the PCGen_experimental Yahoo! group and you can also read their LST Syntax FREQ Usually, items in the issue tracking system as feature requests are already vetted by the _experimental folks, but if it's pretty old or very complicated, a double check doesn't hurt.
  4. Try to change as little of the formatting in the code as possible. Others may look at your PR (to ensure it isn't interacting with other items we are working on that aren't checked in yet), and if the PR is mostly formatting change, one loses the content. If there are formatting changes to be made that are not local to code changes, they should be done in a separate PR. It is preferable to ask permission on significant formatting changes, since they make merging very difficult, and if one of us has a large project we are working on, it can become really hard to keep up and make sure we are actually doing useful work rather than formatting changes.
  5. Given the formatting comment above as more important, there are Coding Standards (for braces and the like).
  6. No major feature changes in a beta cycle - that's what the Alphas are for. Betas fix bugs for releases.
  7. You won't always know everything that is happening... so if you are thinking of major changes, talk to people. If we have sensitive changes going on we will likely speak up, so in rare cases it's good to know where not to be!

Additional Eclipse Tools you may find useful

We run these at various time (PMD and Checkstyle are automated checks we run)

Retrieved from "http://159.203.101.162/w/index.php?title=Basic_Developer_Setup&oldid=4178"