L2J Repository, Commits, Git, GitHub and more...

[Zoey76]

Hello everyone, I'll like to tell you about L2J and it's source code.

L2J is hosting it's projects in GitHub, we moved the whole SVN commit history there, with all the branches for each server version, we have also included our custom libraries.

• Git is a distributed revision control system, for more information please go to: http://git-scm.com/
• GitHub is a free web based Git repository.
• L2J@GitHub

Git is rather different than SVN, in SVN we use to have a local copy of the files at certain revision, we make changes on those files, commit those changes to the remote repository, and synchronize changes made by others on the remote repository. On Git instead of having a local copy of the files, you clone the repository, and instead of committing your changes to the remote repository, you actually commit them to your local repository, and then if you have rights, you can push it to the remote repository.

Index
Getting Started
Updating the source code
How to commit
Branches and Forks
Committing and Pushing
Comment Standard
Links in commits
Crediting

To be added later
Staging
Hard and soft reset
Merging
Conflict resolution
Local Branch
Reverting and Cleaning

[Zoey76]

Getting started

New guide: https://github.com/L2J/L2J_Server/wiki/Setup-Eclipse

SPOILER:

You will need:
A GitHub account
Eclipse IDE for Java Developers
https://github.com/L2J/L2J_Server.git
https://github.com/L2J/L2J_DataPack.git

Source code checkout
In Eclipse, Window->Show View->Other...->Git->Git Repositories:


Now it's required to clone the L2J repository:


Add the following Git https://github.com/L2J/L2J_Server.git URL:


Select the branches you will be using, we have renamed them to be more user friendly, where our master is the former beta branch and stable our former trunk.
For this example, only master will be cloned:


Finishing the repository clone:


(Optional) Importing a project

[Zoey76]

Updating the source code

You need to Pull the changes from the upstream:


The Pull result:


Resolving conflicts and merging
TODO

[Zoey76]

How to commit
I'll assume here that you have checked-out the projects and you are part of L2J organization or you own a fork based on L2J or that you want to commit your changes to your local repository.

In Git, you commit changes to your local repository, then you push them to upstream.

You can perform multiple commits, while working on a feature, documenting in each commit the changes you make, and then when the feature, fix, rework is complete you can push them all at once, if you don't want to popullate the remote repository you can "squash" the commits together and then perform a single commit/push, we will see that later on.

You have to make sure your source is up-to-date, this is, Pull all incoming changes before committing!



In the following window you can write the commit message and the files that will be committed:


Amend a commit
If you Commit, instead of Commit and Push, you can amend your last commit, this means fix commit message, you try to commit again and you will be prompted:


Push to Upstream
If you didn't use Commit and Push option, you can always Push to Upstream by doing:

[Zoey76]

Local Branch
TODO

Forking L2J

To fork L2J and to be able to make Pull Requests (which are cool because they link to your GitHub account), got to the repository page:
https://github.com/L2J/L2J_Server

Click:


Now you can start making changes in your fork, and eventually share your work to improve L2J by submitting Pull Requests.

Happy forking!

Pull Requests
TODO

[Zoey76]

Committing and Pushing

When committing keep in mind this:

• Initiates must always get a review from a Jr. or Sn. developer before committing something, there are exceptions if it's something trivial, do not abuse of this!
• L2J Organization members have cross-commit rights for Core and DP, this is that even if you belong to an specific group you can commit to both projects.
• If you are committing into a project from the other group, remember: This is not your area, always consult someone from the other group, it's not about if you have knowledge, it's about respect, hierarchy and order.
• When pushing, you must have tested it or it must have enough positive feedback, which depends on the commit(s) complexity.
• Pushing untested stuff is not allowed, the only exception is features that are disabled by default until they are finished.
• When fixing a typo/bug try to always refer to the revision where it was originated.
• When fixing a typo/bug from other developer, never exaggerate it, stuff like "fixing server crashed bug" or something that is not actually what it is, it won't be tolerated, remember a team mate's mistake is a team mistake.
• When committing a typo/bug fix always move the reports in forum to Solved/Invalid Bug Reports area and add the tag [FIXED] (if the bug report is invalid add the tag [INVALID]).
• New files cannot be committed without authorship.
• We encourage the use of Pull Requests at GitHub, before merging them into the master branch, they must be reviewed and tested.
• Contributions shared in forum by users that come with no credits or they are from a private or public froks/projects but the author didn't shared it himself: must be ignored and finally archived (or removed by a Sn. developer or higher).
• Always give credits to contributors, testers and reporters.
• Document commits as much as possible, not everyone knows what was in your mind when you did a change.
• Do not commit using empty comments, there is no exception, if you made a typo 3 seconds ago, it's not self explanatory or something like that, you have to make a comment, this is; the right to commit gives you the duty to take responsibilities for your own mistakes.
• Always follow the Commit Comment Standard.
• Take your time to read about JavaDocs and add them in proper way, other team mates can help you with that.
• Try to do spelling check, it's more professional and improves the team's image, also helps users that use automatic translators to get better translations.
• Keep commit comments neutral, do not include stuff such as: "I hate when" or "Fixing stupid bug".

[Zoey76]

Comment Standard

The commit title must represent briefly what the change is about.
Examples:
Fixing Polymorph issue (Packet wasn't updated to H5).
Fixed Town NPC Walkers initial positions and few other minor fixes related.
Removing duplicated code at L2CubicInstance.

Commit comments are recommended in large changes, where code has been formatted or changes are really bigs, try to always add some comments.
Example:
Closing #6251
Please do not use ternary operators for explicit boolean values:
return (EXP1) ? (EXP2) : false;
Instead use:
return (EXP1) && (EXP2);
isSoulshotCharged and isSpiritshotCharged methods should both ask for Player, NPC and Summon.
Fixed comments.

Notes
Using Notes at the end of commit is recommended and it must be used when changes that may put users in troubles, such as library updates, methods rename, implementation changes and files relocation.
Examples:
Note: ternary operators should be used for: EXP ? EXP1 : EXP2; for example.
Note: Do not forget to cleanup your server lib folder!
Note: Requires DP Update.

When implementing missing features, use notes to record to what game version this feature belongs.
For example:
Zaken raid changes.
...
Note: Epilogue feature.

Implementing Freya raid.
...
Note: Freya feature.

In case that the feature has changed over many game versions, such as conquerable clan halls, you can list them the following way:
Conquerable clanhalls:
...
Note: C2, IL, Epilogue feature.

[Zoey76]

Links in commits
Links to Pull Requests:
Use #1 where "1" is the pull request number.

Link to revisions:
Core L2J/L2J_Server@434709f46087bbee439d858492dfba0423d9ce44
DataPack L2J/L2J_DataPack@36fc143365f487e090de7477cd8afea666f5ac2b

For links to forum topics or posts use:
[User Contributions](viewforum.php?f=69)

When mentioning someone use @UnAfraid (use GitHub's username).

[Zoey76]

Crediting

It is very important to record code contributions in a consistent and parseable way.
This allows us to write scripts to figure out who has been actively contributing — and what they have contributed — so we can spot potential new committers quickly.

Code: Select all

Missing feature:Added new feature to the server. Patch by: @nonomTested by: @Andry_85, @malyelfikReviewed by: @UnAfraid, @Zoey76 

Valid tags
Patch by:
Suggested by:
Reviewed by:
Reported by:
Tested by:
Thanks to:
Requested by:

They must be in an own line, no spaces befor nor after, no bracket, no points at the end nor other symbols.
The point is for this tags to be parseable so we can find potential contributors.

In case of multiple names for the same field, they are comma separated.


Crediting own work
The Java code should always include the @author tag in order to get committed.

Contributions without this tag won't be accepted

Crediting existing work
Replacing the author is only allowed when the code have written from scratch or rewritten over 75%~ of the existing code. Of course this cannot be really measured so don't abuse from this.

Adding authorship to an existing file is possible when a feature (non-existing code) has been added or the file has been reworked (existing code), here there is not percent rule, just keep in mind typo fixes, minor bugs or any minor change doesn't count.

When reworking something, usually when we change from a legacy technology, say from static SQL tables to XML files, from Jython scripts to Java scripts, etc, if the move only represents a "translation" it must include (the new file) the original author in the JavaDoc header: First version by UnAfraid.
Is not the case when you replace existing code with new code, but this new code doesn't use the previous code as base and it has been created from scratch and is entirely the contributor's (or contributors') work.

[Zoey76]

Remember everyone, from Team Leaders to Initiates must comply with this standards.

Committing represent taking responsibility of the content of the commit, this is, if you commit your own or someone elses code, if it fails you must have the skills to fix it.

If you don't know how to do something ask, it's better to ask before than fix later.

"I work for free" is not a valid reason to not comply with the standards, if you want to do your own way fork us, just don't fuck us.

Quality it's a requirement along with hard work, if you are not up to it, review what brings you here.a

As finals words you are already probably doing a good work, let's make it an awesome work, okay?