Guide: How to build and submit changes to the git repository

If you'll notice, sometimes it takes a long time for submissions to the project to actually get committed to the main repository. Things get lost in the shuffle, it wasn't clear that this was the final version, the link to the asset died, etc. If you just
post your submission on the forums, it might be a while before you see it in the freedoom autobuilds.

In order to get your submission committed as fast as possible, you could try the method of submitting changes directly to the repository, through what is known as a "pull request".

This guide assumes that your asset is ready to submit. If you're not certain, then post it in the appropriate thread for feedback.

IMPORTANT: Please read the submission rules first:

The general rules go as follows:

You must be incredibly careful when basing on existing graphics or sounds. Most Doom projects are incredibly lax on reusing intellectual property — there are plenty of WADs out there which contain modified Doom sprites, for example. However, due to the nature of this project, we do not have the same liberty to rip as we please.

Everything you submit must be 100% your own work. You must not base upon resources from Doom or any other game. You may not even rip textures from WADs you have downloaded (if you find a WAD with textures in which look useful, let us know — that way, we can contact the author).

Do not simply copy the original resources. Where possible, try to make an effort to make the new versions look visibly different from the originals.

Be especially careful of “free texture” (or “free sound” or “free graphic”) sites. Although these would appear at first to be okay to use, many are free for “non-commercial use only”. One of the things we want to be able to do is put this on GNU/Linux CDs (which are sold — “a commercial use”).

The main exception is that you may of course reuse anything in the Freedoom source tree. In fact, this is encouraged, as reusing material will give the WAD a more consistent feel.





Pull Request Instructions:


Step 1:

Register for a github account if you haven't already: Link


Step 2:

Once you have registered and authorized your account, what you want to do is create a "Fork" of the main freedoom repository (link). What this does is give you your own copy of the freedoom repository to make changes to, and it stores it on your github account.

To do this, click "Fork" at the top right of the main freedoom repository page.



Step 3:

The process might take a while. Once it is finished, what you want to do next is download and install the GitHub Desktop client: Link


Step 4:

Once the Github Desktop client is finished installing and you have logged in to your account, you want to click the "Add repository" button in the upper right, select "clone", then select your freedoom fork and click "clone repository".



Then, select a folder you wish to clone it into, then click OK:



This process might take a while. Depending on the time of day, GitHub might be very slow.



Step 5:

Once the clone process is completed, you now have a full copy of the freedoom repository on your computer to work from. Navigate to the directory where the repository is stored:



Step 6:

edit: Symlinks have been removed! yay!

Just drop your submission into the appropriate folder (sprites, patches, etc.)

IMPORTANT: MAKE SURE ALL YOUR FILE NAMES ARE IN lower case

Step 7:

Now, switch back to the GitHub application. If you'll notice, you'll see that it has kept track of your changes, and lists the files that have been modified.



If you screwed something up and you need to fix something, or don't want to commit a certain file, just right click the file and select "Discard changes"


Step 8:

If everything looks good here, what you want to do next is build freedoom with your changes in place, to make sure everything looks right and it doesn't break the build process. The instructions for setting this up are below.

Step 9:

If you're satisfied that you've included everything that you want to submit, you can then "commit" your changes to your repository. Enter in a brief descriptive title, and and a description of what your submitting and any changes that you have made.

IMPORTANT: For the title, put in which type of submission it is followed by a short description (i.e.: "sprites: new rocket launcher", "patches: new sky patches", etc.).

If you are committing multiple different assets (say, rocket launcher sprites and shotgun sprites), please make individual commits for each. You can select which assets get put into each commit by checking the checkboxes on the left.

If this is a new asset that is replacing an already existing asset, make sure to list what you are replacing.

If this is fixing an issue documented on the repository (link), then include the issue number with the "#" sign (e.g. "issue #150")






Step 10:

Once your satisfied with that, then click the "Commit to Master" button.

If right after this, you realized that you didn't want to make that commit, you can click the settings button in the upper right corner, and click "Undo most recent commit"



Step 11:

Once the changes are committed, you can then finally create the pull request. Just click the button in the upper right.



This should be filled out automatically if you have a single commit. Tf you have multiple commits, then you should summarize them in the title and description.


Step 12:

Click "Send Pull Request"! That's it, it's all done.

You can view the pull request's status online to see if it's been merged yet:




Once the pull request has been merged, you can see your changes in the latest freedoom autobuilds (daily builds at 2:30am GMT)


**************************************
**************************************


Building and testing your submission.

Before you commit your changes, you might want to test to make sure everything looks right and it doesn't break the build process.

Cygwin is usually a pain to set up for building freedoom, so I've come up with a relatively painless way to setup Cygwin that is ready to build freedoom.


Step 1:

Download the MobaXterm installer, and install it.

MobaXterm is a cygwin shell replacement that I find a bit easier to set up. It also allows plugins.


Step 2:

Download my custom deutex plugin.

This allows you to use deutex without having to build it from source.

Copy it to the directory where you installed MobaXterm. This should be "C:\Program Files (x86)\Mobatek\MobaXterm Personal Edition"



Step 3:

Open up MobaXterm, and start a "local terminal"



Step 4:

At the local shell, copy and paste this string:

apt-get install make python ImageMagick ghostscript-fonts-std

this will install all the additional packages needed to build Freedoom.


Step 5:

Copy and paste this command:

rm /usr/share/fonts/misc/helvB*.pcf

This fixes a bug with the fonts that messes up the build process.


Step 6:

Once all the packages are installed, change your directory (using the command "cd") to where your local copy of the repository is stored. By default, this should should be "MyDocuments/GitHub/freedoom/"

Note: if it's stored in a place other than your desktop or your documents, you'll have to go through the windows directory structure by going to "/cygdrive" first.


Step 7:

Type "make". That's it.

If you're building after already having done another build, type "make clean" first. This will get rid of all the previously built files.


Step 8:

Now that the files are made, you should find the built wads in the "wads" folder in your repository. Run these with your favorite source port and make sure your changes are in place and that everything looks right.

Share this post


Link to post

Now that symlinks are removed, pulling the git repository and building it on windows is simpler than ever. I have updated the pull request guide and added a guide to easily set up the build environment and build freedoom.

Share this post


Link to post

If your pull request gets closed without being merged, or if it had to be modified somehow, your fork will be out of sync with the official repo, and you can't automatically update it. This can lead to problems with future pull requests.

To fix this and to reset your fork to the current official repo state, do this:

open mobaxterm, go to your fork directory

Type "apt-get install git", which will install the command-line version of git.

type "git fetch freedoom master", which will retrieve the current version of the official repository.

type "git reset --hard freedoom/master", which will reset your local copy to the current version of the official repo.

type "git push --force origin master", which will reset your fork on github to the current version of the official repo.

It'll ask you to type in your name and password, and it won't show you typing the characters for them. Just keep typing, it's getting it down.

Share this post


Link to post
Doctor Nick said:

type "git fetch freedoom master", which will retrieve the current version of the official repository.

I just tried this on my fork, and it produces this error:

fatal: 'freedoom' does not appear to be a git repository
fatal: Could not read from remote repository.
Is that because "freedoom" is not setup as a known remote (via git remote) ?

Share this post


Link to post
andrewj said:

I just tried this on my fork, and it produces this error:

fatal: 'freedoom' does not appear to be a git repository
fatal: Could not read from remote repository.
Is that because "freedoom" is not setup as a known remote (via git remote) ?


It should do that by default if you use the github application. either way, all you have to do for that is type "git remote add freedoom https://github.com/freedoom/freedoom.git"

Share this post


Link to post

I used the "fork" button in github, and then "git clone ..." here on the command line (Debian Linux).

Cheers for the info.

Share this post


Link to post

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now