-
Notifications
You must be signed in to change notification settings - Fork 25
Developers Guide
This guide is still in progress. For now, it incorporates some of the lessons learned and best practices/methods we wish to use in this project.
We're attempting to get this project organized and follow some basic general rules to make everyone's life easier.
Branches:
- master - This will hold the latest, stable "milestone". Pushes should only happen to master when we're releasing a new milestone or hotfixing something important.
- dev - This is where project maintainers will pull in merge requests and do most of the day to day coding work.
Preferably, no one will push direct to either of those branches. (maybe dev is an exception. smitty?)
Work should mostly be done in feature branches and then merged in.
Those familiar with professional standards of software development will quickly notice that the codebase for this project is lacking in many ways. It is the accumulation of thousands of man-hours of many developers (both amateur and pro) over the course of 12+ years. Given that history, it is by its nature going to have many conflicting ideas, dead-ends, abandoned blocks of code, and so on. Even the best practices in software development have changed over the time this project has been active.
Given the manpower available, it's simply unfeasible to expect anything resembling perfection. Even billion-dollar companies have legacy codebases every bit as bad as what you'll find here.
An incomplete list of the things we know are wrong with the codebase:
- Inheritance: The server code has deep, hard to navigate inheritance hierarchies. This would probably be less of an issue were it not for the fact that not everyone who's ever worked on the project shared the vision of the original creators of the game's custom types. Additions sometimes have ended up in the wrong, or at least suboptimal, place as a result.
- Spaghetti: Partially related to the above, tracing through the code sometimes results in way too much deep referencing, making it hard to tell where the controlling code for a certain action is.
- Naive DBMS design: No foreign keys, inconsistent naming, etc.
- Dated tech stack: Modern Java development has moved on from some of the dependencies we use here, though the ones we have here are pretty stable. Some replacements have already happened.
- Design pattern impedance mismatch: Some of the previous developers loved design patterns. These work better in isolation, but when multiple patterns meet, sometimes they do so poorly. They're also a challenge for those uninitiated in pattern usage.
Finally, probably the largest impediments to correctness in code are due to two fundamental natures of the project as a server emulator:
- Proper debugging isn't possible due to the way the code runs and the lack of a test suite.
- The client is a black box. The client is proprietary and closed source. That means we can't tell what it's doing internally, and can only observe its effects by trial and error.
All of these factors result in a challenging development environment. However, one should not despair too much. There are certainly worse codebases out there still under active development and critical to the technology infrastructure that you depend on to live (cough Linux kernel cough). As long as we keep in mind the true state of affairs, we can adjust expectations accordingly. This guide also serves as a means to make sure the project heads in a direction that minimizes and slowly rectifies these downsides.
Firstly, familiarize yourself with Git. The common standard is the git
command line tool, but there exist many plugins for your favorite IDE/editor
and even full GUI front-ends. Know, however, that no Git tool fully
encompasses all of things that one might want to do with Git. Support for
various tools is also spotty. Thus, be prepared to drop back to the command
line if you need to do something complex.
When making commits to the repo (or one to eventually be merged), do everyone a favor and read this guide on how to compose a proper commit message. A messy commit log makes more work for others scanning the log, trying to nail down when something broke.
See the branch policy section for knowing where to put what commit.
Commits should be either one change, or one complete feature. Please don't spread out one feature over a ton of individual commits. It makes merging and tracking harder. Sometimes that'll happen anyway, and that's okay, but avoid it where it's sane to do so. Also if you're making a ton of whitespace/formatting changes, please commit those seperately from actual code change commits and try to aggregate them. Again, it makes it easier to diff and keep track.
Please don't create more "global"/"public" branches without permission from the dev team first unless they're short term/temporary branches. Lots of branches confuse new users and syncing a lot of branches is a chore that is likely to not get done.
Keeping in mind the above comments about acknowledging reality, we should strive to write readable, maintainable code that is no more complex than it needs to be to get the job done.
This is a hard guideline to codify, so use your best judgment on what constitutes the previous statement. Some examples might be:
- If you're going to rewrite 70% of a class, you might as well redo all of it and tidy the whole thing up.
- If you're adding some methods, take a moment to think about where they should go in the class hierarchy, instead of just sticking them somewhere in the call path that gets the job done.
- When rewriting some existing code or writing new code, choose names for variables and types that are Java-standard and communicate intent clearly.
- If you work to unravel a big mess and finally figure out how it works, maybe take a stab at simplifying it while you've already paid that overhead cost. Otherwise the next person that comes along will have to do all of that unraveling again (and that could easily be you, years later).
- Try to minimize excess whitespace and do a formatting pass on any new/modified code before committing.
A few caveats apply to the database. Since any database naming changes have to be synced with the Java ORM code, be a little more conservative about changing things here. Some users are a little sloppy about making sure the two tiers are in sync and any changes will result in a lot of support questions for the staff. Refactoring the database is fine, but try to aggregate changes into large, important changes. The best time to do it is at the end of milestone builds.
TODO: Consider selecting a published Java coding standard to standardize upon for the project.
When in doubt, of if you're just learning dev tools like Git, feel free to ask. Many have started from nothing and were making substantive contributions to the project in short order, and the team is generally happy to lend a hand. Don't let any of these guidelines scare you away from helping either. For example, you can experiment locally and migrate changes over to a fresh copy of the repo before doing a push or merge request.
Due to the competitive and PVP-centric nature of Lineage, there are many rivalries, some stretching back to the live servers. None of us developers actually play the game except as GMs, so we're not involved. Please keep any in-game squabbles there, or really anywhere else.
We don't have any lengthy code of conduct (as is popular in software development these days). There's only one rule: don't be a dick. Or at least don't be a dick around us, in the IRC channel, or on any of the developer resources. If you want to do that, log into the game or get a Twitter account.