Organization of DFHack on github:DFHack's main (and top) repository ("repo") on github is
https://github.com/DFHack/dfhack. DFHack also has sub repos for structures (
https://github.com/DFHack/df-structures) and for scripts (
https://github.com/DFHack/scripts). In addition to these, there are sub repos for various large plugins (most plugins are included in the main repo).
The df-structures sub repo contains XML representations of the DF data structures mapped out. This representation is used to automatically generate .h files as well as some underlying code that is then used by the main repo code. However, it should be pointed out that these generated files are NOT present in any of the repos: they're generated as part of the build process and thus appear on machines where DF is built, but you can't find them in the repos.
When DFHack is "cloned" to a local computer, the cloning process stitches the main repo and the sub repos together, so df-structures gets placed into the DFHack structure as dfhack\library\xml (where "xml" basically substitutes for "df-structures") and "scripts" is placed at dfhack\scripts (without any name change).
The DFHack/dfhack repo essentially operates with two "branches": the "master" branch, which should contain the contents of the latest release, and the "develop" branch that is where updates on the road towards the next release are made.
The DFHack/df-structures and DFHack/scripts repos, in contrast use the "master" branch for development, with releases being frozed in "tags" (the DFHack/dfhack repo uses tags as well).
Working with git to update DFHack:If you already know how git works this is probably redundant. It should also be pointed out that there are several ways of achieving things with git so the ways described should not be takes as the only or best way, just one that ought to work.
git uses "pull requests" to get things incorporated into the appropriate structure. They are "requests" to "pull" submissions into the maintained structure, which essentially corresponds to submitting the proposed updates for review and acceptance. Once a pull request (PR) has been made, people authorized to update the repo can comment and request changes until they're satisfied with the results, at which time the changes are "pulled" into the working repo. It should also be noted that git pull requests operate on the whole repo, so a PR consists of the complete repo with the changed files included, as opposed to other systems where you would submit only the changes. Internal git logic handles the issue of the official repo moving along while you made the changes, so if some of your unchanged files lag behind the official ones is not a problem (unless, of course, your changes result in conflict with those made by others).
In order to make a PR you have to have your own "fork" of the repo on github. The fork's master and/or develop branch content essentially doesn't matter: you don't have to try to synchronize them with the official repo contents. Instead, you create transient branches that act as storages for each PR until the PR has been accepted, at which time the branch is deleted.
The real work, however, is made locally in your clone.
git can be operated from the command line at the top directory level of the repo (i.e. inside dfhack, xml, or scripts).
Note that DFHack repos are separate entities from a git point of view, so the dfhack, df-structures (a.k.a. xml), and scripts repos each operate on their parts of DFHack. This means that if you e.g. work on a script you have to work in the scripts directory.
When you clone DFHack to your computer a "remote" reference named "origin" is created. This can be seen with the command "git remote -v". However, in order to eventually create a PR you need to get your changes up to your fork, and that requires that you set up a "remote" referencing that repo, which can be done with "git remote add upstream <path of your repo>" to add a new remote reference called "upstream". Once done, "git remote -v" lists both remote references. As indicated above, this is set up independently for each repo.
Unless you've just cloned DFHack, you typically want to refresh your clone repo at the level you're working on. This is done with "git checkout develop" or "git checkout master" depending on whether you're in the main DFHack repo or in a sub repo, to ensure you're starting from the correct branch, followed by "git pull origin" [Is that correct, or are there pre conditions?].
Once there, you typically follow it up with "git branch <the name of the transitory branch your PR will use>" to create a branch and "git checkout <the name of the transitory branch your PR will use>" to switch to it. This should cause the new branch to start out the same as the newly refreshed develop/master branch.
Once you've made the changes you want to make, you need to tell git that you want the changes to be noted. The command "git status" shows files changed, including relative paths, if any. To tell git you want the changes to be included, you issue the commands "git add <file name as show by 'git status'>" and "git commit <file name as show by 'git status'> -m "short commit comment"". Don't forget the -m comment switch, or you're going to be tossed into a vi editor clone to write a comment, which is "fun" if you don't know vi.
Once you've committed all changes, use "git status" to check that all outstanding changes have been committed.
The next step, assuming you've created a branch for the changes on your github repo fork (if not, do that now) is to push the changes up to the repo fork branch with "git push upstream", which may require you to enter username/password. After that, go to you web browser to verify that the changes are actually present.
Time to make a PR using the web interface. Check the diffs presented to verify that this is actually what you wanted and that all of it is there. Also make sure there aren't any unintended changes resulting from someone else updating a file while you were working on it (if there are, abort the pull request, update your files to incorporate those changes, test it, and redo the commit/push steps before retrying to make a pull request).
Author
Topic: DFHack 50.14-r1.1 (Read 893492 times)