Development Practices

This page is devoted to describing the best practices, methods, and policies that EVEmu Developers espouse to uphold while working on the EVEmu Project. All Developers are expected to follow these guidelines and policies all in the effort to ensure a smoothly executed development process and collaborative effort to produce great quality code and a great product.

Source Control

TODO: describe how we use github, git, repos, branches, tags, and merges.

GIT:

• Our process for developers to contribute:
  1. Get your own account on Github and Fork the evemuproject repository for which you wish to contribute (evemu_server, evemu_control_panel, etc)
  2. Git clone your fork on github to your local machine - Github's help on forking a repo and cloning it
  3. Make some changes to code as you work on a feature implementation, enhancement, or bug fix
  4. Commit those changes with a descriptive commit message (see below at Commits)
  5. If the feature is not working yet because you have more changes to make, repeat the previous two steps until you have something worth posting up for the community to review and try out
  6. When you're ready to post a bundle of commits as a Pull Request, first, exit Visual Studio, then RE-run CMake Configure then Generate. Open Visual Studio again and do a FULL REBUILD of the ALL_BUILD project. When the build is finished, run the server and in the console window, ensure the version: reads the latest tag, the master branch, and your latest commit ID, something like 0.7.12-master-ba5d6d3. The first three numbers are the tag (at git cmd line, type git tag to list all tags, see which is highest). The middle string is your branch (should be master unless you're working on a parallel branch). The last is your latest commitID (at git cmd line, type git log --oneline and at top of that list on the left is your latest commitID showing the first 7 digits or so).
  7. After you've ensured your build matches the latest tag and commitID, go to your Github account page under your fork of the repository you're working on, then either click on the green square button to the left of the branch change drop-down (below the # of commits display) OR click on the label Pull Request to the upper right of the area that lists the folders and files in your repository. It's to the left of a label Compare in the heading bar above the list of files and folders.
  8. Next, click the button with blue box border labeled Click to create a pull request for this comparison
  9. Right away, Github gives you feedback on whether the maintainers of the repository to which you're pushing a pull request will be able to automatically merge your pull request's changes. If you don't get the green check mark and the message Able to merge, then you'll need to bring your fork up to date with the original repository and try again.
  10. If you do get the green check, enter a Title and Description for your pull request and click Send Pull Request button and away it goes!
  11. Please be patient as it will take some time for the EVEmu Development team to review and discuss, perhaps even test, your pull request's changes. It may even be rejected, but the team will provide some helpful comments on the pull request whether it has been rejected or not. These things are often an iterative process, so be patient and be prepared to expect to have to make further changes before the development team accepts the pull request. The higher quality code changes you make and the more you discussed the changes with developers ahead of submitting the pull request, the more likely your pull request may be accepted on the first round after some review period.

Commits:

• when making commits, keep them small, a few files or so, and commit OFTEN! this leaves you nice history of your work as it progresses
• when making commits, either use a GUI such as SmartGitHg or git gui to write your commit messages, stage files for commit, and ultimately commit the changes and even push them up to your fork for issuance of a pull request to the main evemuproject project page
• write commit messages that make sense and are descriptive enough to tell others what you did and why
  • BAD Commit message: i changed some code
  • MEH Commit message: i added some classes to the module manager
  • BEST Commit message: Added Effects, EffectsMap, and ShipBonusModifierMap classes to the ModuleManager effort. Updated SQL files for the following tables 'dgmEffectsInfo', 'dgmShipBonusModifiers' to match the data pulled and reformatted from EVEHQ CSV files. Added completed LibreOffice spreadsheets for the following EVEHQ CSV files: Effects.ods, ShipBonuses.ods, SkillBonuses.ods
• when making commits as part of a larger effort, such as to fix Private Convos in the LSC system, or implement P2P trades in the Trade Service, keep your commits local until you have a feature working, then post up a pull request with a bundle of commits rather than posting pull requests for each small commit you make
• PLEASE....after making a pull request, wait until it has been approved before committing additional files to avoid unnecessarily large PRs.

Coding styles and standards

While we do not have a formal coding style guide, let me put it as simply as I can:

• Please stay within the spirit of the design and styles that you see already being used in the code, to the extent that you can. Functions and Methods use the lowerCamelCase naming convention. C-type macros and #DEFINEs use ALL_UPPERCASE with hard spaces. Variables are named as to their intended use, where possible, and use lowerCamelCase also.
• Please do not do major edits of whitespace all over (changing tabs to 4-space chunks, making separation between functions 2 lines instead of one, etc)
• Please do not make large edits of comments, but rather keep them compartmentalized into sections of code, such as within the LSC chat system or Ship class

Bug reporting

Every bug should be reported on our github's project page

IMPORTANT - Before posting a bug, please take a few minutes to search the bug database for the project you're working on to see if someone else already reported the bug. If this is similar to another bug or bugs, we can link them together, but it's ok to post a new bug if there are aspects about it that are unique from the other similar bug reports.

Please post bugs using the following format:

• PROBLEM
  • Describe what the problem is and what you were doing when it occurred. Please post server console log in EVEmu's Pastebin and mark expiration as NEVER, then post a link to that pastebin in this section. Feel free to upload to imgur.com or other photo sharing site a screenshot of the client if applicable when something weird or unexpected happens and link to the image in this section.
• STEPS TO REPRODUCE
  • In this section, please describe in as best a detail and accuracy as you can the steps someone else must take in order to reproduce this problem. It is absolutely essential that developers and bug fixers have these steps as they must be able to reproduce the bugs or crashes in order to start investigating them and eventually fix them. We certainly understand if you cannot recall or are somehow unable to describe how the problem occurred. If that is the case, please do your best in describing how you came about the crash or bug and what you were doing leading up to when it happened.

• WORKAROUNDS
  • This section is meant to capture known methods by which you can accomplish what you were trying to do, but in a slightly different way. An example could be "I was trying to buy something off the market, but opening up the market window crashed the server." For this, a possible effective workaround would be "I can still use .create GM command to give myself the item I wanted."

• PROPOSED SOLUTIONS
  • This section is really reserved for developers posting bugs that may be somewhat or very familiar with the systems behind the scenes in the server that relate to the bug or crash. This section is meant to be a notepad of sorts to jot down ideas as to how the problem could be fixed or circumvented when they are fresh in the mind of the developer that encountered the bug or crash. Most users and testers may leave this blank unless you think you have a good idea :)