Difference between revisions of "WesnothRepository"

From The Battle for Wesnoth Wiki
Line 1: Line 1:
 
{{Compiling Wesnoth}}
 
{{Compiling Wesnoth}}
  
The Battle for Wesnoth code base is stored in a version control repository. Version control allows the entire dev team to edit files concurrently. The software tracks revisions, stores a record of all edits, revents simultaneous editing from causing clashes. All changes are stored in the version control repository.  
+
The Battle for Wesnoth code base is stored in a ''version control repository''. Version control allows the entire development team to edit files concurrently. The version control software tracks revisions, stores a record of all edits, and prevents simultaneous editing from causing clashes. All changes are stored in the version control repository.  
  
 
When a release is planned, the current set of the files in the repository is frozen, given a release number, and shipped out to the world at large. Then, as files continue to be edited by the developers, the repository code advances past that point. The repository (or "repo") version is by definition the most up-to-date version of the code.
 
When a release is planned, the current set of the files in the repository is frozen, given a release number, and shipped out to the world at large. Then, as files continue to be edited by the developers, the repository code advances past that point. The repository (or "repo") version is by definition the most up-to-date version of the code.
  
The Wesnoth repository uses Git and lives at https://github.com/wesnoth/wesnoth-old
+
The Wesnoth repository uses Git and lives at <https://github.com/wesnoth/wesnoth-old>.
  
== Git ==
+
== Git ==
  
Git is the most widely used open-source version-control system. You can learn more about it at the Git home page, http://git-scm.com/.
+
Git is the most widely used open-source version-control system. You can learn more about it at its website, <http://git-scm.com>.
  
Git replaced Sub&shy;&shy;version as Wesnoth's version control system in March 2013. Sub&shy;&shy;version had itself previously replaced an older program called "CVS" or "concurrent versioning system" in 2005. These earlier systems have left a few traces in the version history which you might encounter; some older documentation and a few files refer to them.
+
Git replaced Sub&shy;version (SVN) as Wesnoth's version control system in March 2013. Sub&shy;version had itself previously replaced an older program, Concurrent Versioning System (CVS), in 2005. These earlier systems have left a few traces in the version history which you might encounter; some older documentation and a few files refer to them.
  
 
==  Browse the code  ==
 
==  Browse the code  ==
Line 21: Line 21:
 
==  Download  ==
 
==  Download  ==
  
To check out a read-only copy into a directory called ''wesnoth'',
+
To ''clone'' a copy of the repository into a directory called ''wesnoth'',
  
  git clone git://github.com/wesnoth/wesnoth-old.git wesnoth
+
  git clone https://github.com/wesnoth/wesnoth-old.git wesnoth
  
 
==  Commit access  ==
 
==  Commit access  ==
  
For commit access, you must have a developer account on GitHub, it must be registered as part of the Wesnoth group, and you must check out with:
+
For commit access, you must have an account on GitHub, which must be registered as part of the Wesnoth group.
 +
 
 +
It may be convenient to use Secure Shell (SSH) transfer, so that you needn't enter your username and password each time you push commits, or insecurely store those credentials in an unencrypted configuration file. To do so, generate an SSH ''key pair'' with a command like (on Unix descendent operating systems like a Linux distribution or Apple OS X, at least) this:
 +
 
 +
ssh-keygen -t rsa -b 15360 -f <file> -C "<your name>'s SSH key for GitHub"
 +
 
 +
On Linux or Apple OS X, <file> would be, e.g., "~/.ssh/id-key-for-github".
 +
 
 +
Then put the following into your SSH configuration file (on Unix descendent systems, this is "~/.ssh/config"):
 +
 
 +
Host github.com
 +
IdentityFIle <file>
 +
 
 +
Then register the key with GitHub, by going to <https://github.com/settings/ssh>, selecting "Add SSH key", and pasting the contents of the ''public key'' file (<file>, but with a ".pub" extension) into the "Key" field.
 +
 
 +
Then, if you have not yet cloned the repository, clone it via SSH:
  
 
  git clone git@github.com:wesnoth/wesnoth-old.git wesnoth
 
  git clone git@github.com:wesnoth/wesnoth-old.git wesnoth
 +
 +
If you have already cloned the repository, you can set it to use SSH transfer:
 +
 +
git remote set-url origin git@github.com:wesnoth/wesnoth-old.git
  
 
==  Update  ==
 
==  Update  ==
Line 51: Line 70:
 
   git format-patch HEAD~1..HEAD
 
   git format-patch HEAD~1..HEAD
  
or something similar; "HEAD~1" may be replaced by a hash or symbolic reference to any earlier revision. This will produce one or more patch files, numbered and endingth with the extension ".patch".  See [[PatchSubmissionGuidelines]] for more on how to get these merged into the public repository.
+
or something similar; "HEAD~1" may be replaced by a hash or symbolic reference to any earlier revision. This will produce one or more patch files, numbered and ending with the extension ".patch".  See [[PatchSubmissionGuidelines]] for more on how to get these merged into the public repository.
  
 
== Push to your own fork ==
 
== Push to your own fork ==
  
If you have an account on github, you can fork the repository and add your fork as a remote to your clone.
+
If you have an account on GitHub, you can fork the repository and add your fork as a remote of your clone.
  
 
   git remote add fork git@github.com:YOUR_USERNAME/wesnoth-old.git
 
   git remote add fork git@github.com:YOUR_USERNAME/wesnoth-old.git
  
You can then push your feature branches to your fork.
+
You can then push your branches to your fork:
 +
 
 +
git push fork branch_name
 +
 
 +
Or, if you want to push one branch in your local repository to another in the remote repository:
  
  git push fork local_branch_name:remote_branch_name
+
git push fork local_branch_name:remote_branch_name
  
Feature branches can be used to base pull requests on using github's webinterface.
+
You can then create pull requests from your branches in GitHub’s Web interface.
  
 
== See Also ==
 
== See Also ==

Revision as of 17:10, 5 January 2014

[edit]Compiling Wesnoth

Platforms

The Battle for Wesnoth code base is stored in a version control repository. Version control allows the entire development team to edit files concurrently. The version control software tracks revisions, stores a record of all edits, and prevents simultaneous editing from causing clashes. All changes are stored in the version control repository.

When a release is planned, the current set of the files in the repository is frozen, given a release number, and shipped out to the world at large. Then, as files continue to be edited by the developers, the repository code advances past that point. The repository (or "repo") version is by definition the most up-to-date version of the code.

The Wesnoth repository uses Git and lives at <https://github.com/wesnoth/wesnoth-old>.

Git

Git is the most widely used open-source version-control system. You can learn more about it at its website, <http://git-scm.com>.

Git replaced Sub­version (SVN) as Wesnoth's version control system in March 2013. Sub­version had itself previously replaced an older program, Concurrent Versioning System (CVS), in 2005. These earlier systems have left a few traces in the version history which you might encounter; some older documentation and a few files refer to them.

Browse the code

There are currently two main streams of development: trunk (1.11.x) and stable branch (1.10.x). Most other branches are only used for a short time to do some testing without disturbing the main development. You can use your web browser to navigate through the source code:

https://github.com/wesnoth/wesnoth-old

Download

To clone a copy of the repository into a directory called wesnoth,

git clone https://github.com/wesnoth/wesnoth-old.git wesnoth

Commit access

For commit access, you must have an account on GitHub, which must be registered as part of the Wesnoth group.

It may be convenient to use Secure Shell (SSH) transfer, so that you needn't enter your username and password each time you push commits, or insecurely store those credentials in an unencrypted configuration file. To do so, generate an SSH key pair with a command like (on Unix descendent operating systems like a Linux distribution or Apple OS X, at least) this:

ssh-keygen -t rsa -b 15360 -f <file> -C "<your name>'s SSH key for GitHub"

On Linux or Apple OS X, <file> would be, e.g., "~/.ssh/id-key-for-github".

Then put the following into your SSH configuration file (on Unix descendent systems, this is "~/.ssh/config"):

Host github.com
	IdentityFIle <file>

Then register the key with GitHub, by going to <https://github.com/settings/ssh>, selecting "Add SSH key", and pasting the contents of the public key file (<file>, but with a ".pub" extension) into the "Key" field.

Then, if you have not yet cloned the repository, clone it via SSH:

git clone git@github.com:wesnoth/wesnoth-old.git wesnoth

If you have already cloned the repository, you can set it to use SSH transfer:

git remote set-url origin git@github.com:wesnoth/wesnoth-old.git

Update

Do this from inside the wesnoth directory

git pull

Reviewing your changes

Before committing, it's always wise to run

git diff

and look at the output. Some kinds of mistakes that are hard to see embedded in all the code you have modified are more easily spotted in the isolated diff lines.

Generating patches

Under Git on a Unix-like operating system, you'll typically do

 git format-patch HEAD~1..HEAD

or something similar; "HEAD~1" may be replaced by a hash or symbolic reference to any earlier revision. This will produce one or more patch files, numbered and ending with the extension ".patch". See PatchSubmissionGuidelines for more on how to get these merged into the public repository.

Push to your own fork

If you have an account on GitHub, you can fork the repository and add your fork as a remote of your clone.

 git remote add fork git@github.com:YOUR_USERNAME/wesnoth-old.git

You can then push your branches to your fork:

git push fork branch_name

Or, if you want to push one branch in your local repository to another in the remote repository:

git push fork local_branch_name:remote_branch_name

You can then create pull requests from your branches in GitHub’s Web interface.

See Also