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

***UPDATED 8-3-2017: New build process, see below

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:
 

Quote

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.

Quote

http://i.imgur.com/R3ud11J.png?1

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".

Quote

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

Quote

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:

Quote

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.

Quote

http://i.imgur.com/1drHR8l.png?1

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"

Quote

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")

Quote

http://i.imgur.com/aoXzLot.png?1

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"

Quote

Step 11:

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

Quote

http://i.imgur.com/7ep3Pfp.png?1

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:

Quote

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


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

 

**UPDATED 8-3-2017**
 

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:

**UPDATED 8-3-2017**
 

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"

Quote

Step 3:

Open up MobaXterm, and start a "local terminal"

Quote

Step 4:

At the local shell, copy and paste these strings:

apt-get install libpng16 make python python-pip

pip install pillow

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

Quote

 

Step 5:

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 6:

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 7:

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.

Edited August 4, 2017 by Doctor Nick : new build process

Thant's really helpful, thanks

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.

Request for this thread to be stickied?

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.

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) ?

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"

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

Cheers for the info.

Awesome guide, but should the moderators attn this?

The Build process has been updated, please see the new instructions.

Q: how exactly did you build the MXT3 plugin?

1 minute ago, Voros said:

Q: how exactly did you build the MXT3 plugin?

I just took the deutex binary, put it in the proper root-level directory structure (/usr/bin), and then zipped it, and then renamed it to mxt3. mxt3s are just zip files that get extracted to the root of the cygwin installation.

So it's just a zipped deutex executable? If so, that means basically anyone can make it, right?

Does it matter if it's in another directory?

It's the deutex executable in the directory structure /usr/bin. I put in /usr/bin because that's included in $PATH by default, but it could be in any directory. 

 

Anyone can make it, yeah.

You should mention that in the OP :) because most of us probably thought it needed some fancy steps to build it, if you get what I mean.

Could I apply this for Apple™