CONTRIBUTING.md

Contributing to the Xastir project

Hello possible new developer, and welcome to the Xastir project!

Ways to contribute

There are many ways to contribute to a project, and not all mean that you have to write code.

• You can ask and answer questions on the Xastir mailing list
• You can report bugs
• You can fix bugs
• You can add or modify features in Xastir

Asking and answering questions

Please subscribe to our mailing list as listed on the official Xastir web site, http://xastir.org/. We would prefer it if you would not use Xastir's git hub issue tracker just to ask questions, as this is not the ideal forum and doesn't reach the full Xastir user community. Your best bet is to get your question in front of as many users' eyes as possible, and the mailing list is the way to do that.

Once you're confident enough with Xastir to be answering users' questions, your presence on the mailing list will naturally allow you to see and answer those questions, too.

Reporting bugs

If you believe you might have found a bug, your first step might be to ask about it on the mailing list to see if it's really a bug, if you're making a mistake, or if it's just a difference between what you expect and what the code actually does.

If you are reasonably sure that you have found a real bug and wish to report it, open an issue on the Xastir Github repository at https://github.com/Xastir/Xastir.

Realize that Xastir is entirely a volunteer effort largely moved forward by very busy people, and your bug might not get fixed in short order, and it might not even get fixed unless you fix it yourself.

Fixing bugs

Another way you can contribute is to fix bugs yourself and submit pull requests to the group for your changes to be added to the main code base. You could fix bugs that you find yourself, or could look through the existing list of issues on Github and pick one to fix.

If you do this, you will want to follow the procedure below that describes how to submit code changes for review and acceptance.

Adding or modifying features in Xastir

Maybe Xastir is lacking some feature you really want, or you really would like to make some other feature of Xastir work differently. The first step here might be to start a discussion on the mailing list to see if other users like your addition or modification before pressing ahead with it, but you could always just go ahead with the development and offer it as a suggested change through the pull request mechanism. Asking on the mailing list first is more likely to get a faster response when your pull request shows up..

General guidelines for contributing code

In order to get contributed patches accepted more easily by the Xastir developers:

• Read "Developer Guidelines and Notes" in the "HowTos" section of Xastir's Wiki (http://xastir.org). Make sure to follow the formatting and indentation rules, and in particular the tab format (spaces, not tabs). If you don't like some of the formatting rules, abide by them anyway for consistency. Some of the developers don't like some of the formatting rules either, but consistency is more important than ideas we might have of coding style!

• Check the Xastir issue tracker: http://github.com/Xastir/Xastir/issues You need a GitHub account to create new issues, but this is free. This is one of the best places to see what needs to be worked on, and to see if anyone else has had a similar idea.

• Check with the Xastir-Dev list first to see if anyone else is working on that particular idea or section of code.

• Verify on the Xastir-Dev list that your idea has some merit and chance of being accepted before you put your valuable time into the patch.

• Make sure you're willing to abide by the GPL license with respect to your patch.

• Use as generic C as possible, and comment what you've done, in English please!

• Keep in mind that Xastir runs on multiple operating systems, so code for that. Some #ifdef's may be required in order to make it work for the various operating systems.

• Xastir can be run in multiple languages, so code for that. If any user text is added, make sure to add language strings for them to the language files. If you don't know a particular language, add it to all of the language files in English. It will be translated by others later.

Contributing code changes to the project

While it is always possible to create a patch set and email the result to Xastir developers, this is no longer a desirable way to proceed. The preferred method of contributing source changes is through GitHub "pull requests." (See https://help.github.com/articles/about-pull-requests/)

In a (rather large) nutshell this process goes like this:

• Log in to Xastir's github repo at https://github.com/Xastir/Xastir.git and click the "Fork" button. This will create a copy of the repo that you have full control of. Once you have created a fork, here's a general approach you can use:

• Clone your repo:

  cd <some place other than where your other Xastir clone lives>
  git clone https://github.com/youruserid/Xastir.git
  cd Xastir
  

  The result of this step is that you will have a primary remote named "origin" that points at your forked repository. It will also have checked out the default branch, which in the case of the Xastir repo is just the "master" branch.

• Add the official repo as a second remote called "upstream":

  git remote add upstream https://github.com/Xastir/Xastir.git
  

  Now your local repo knows about two remote repos -- yours, and the official project repo. Now make git sync to this remote, too:

  git fetch upstream
  

• Create a topic branch to work on:

  git checkout -b <branchname>
  

• Do all your work while checked out in this branch. As you work, use git add/git commit commands to save your changes in logical chunks. Staging your changes in multiple commits this way helps keep the project history readable.

  See the notes below regarding formatting of commit messages, please.

• When you have finished your work (or when you think you have) and are ready to ask for it to be reviewed and accepted, you will need to publish your changes to GitHub and initiate a pull request.

  • First, make sure your repo has an up-to-date master branch:

    git fetch upstream            # This fetches changes in the official rep
    git checkout master           # go back to the master branch
    git merge upstream/master     # brings your local master up to date
    git push origin                 # this brings your GitHub fork up to date
    git checkout <branchname>       # get your branch back
    

  • Always rebase your feature branch so that it branches off of the current head of the master branch:

    git rebase master               # makes sure that your branch is based
                                    # on the most recent version of master
    

  • Now publish your branch in your GitHub fork (your "origin" remote).

    git push -u origin <branchname>
    

    Now your changes exist on the named branch in your GitHub repo, and may be shared with others.

    NOTE: If you have refrained from touching the code on the master branch, the merge of upstream master will always be as simple as shown here, with no conflicts possible --- all you're doing is grabbing what others have done while you were working. In times of great activity on master (there are seldom such times) it is possible, though, that the rebase operation can show conflicts between upstream changes and your changes that you will have to fix yourself. Resolving these conflicts requires editing your code, fixing the conflict markers, then doing additional git add/git commit operations and a third command to tell git rebase to continue after the conflict resolution. Please see the Pro Git book at https://git-scm.com/book/en/v2 for guidance should this happen to you.

  • A good practice at this point, before you've asked the Xastir developers to merge your work, is to send an email to the xastir-dev mailing list and ask others to test out your work. They can easily check out your fork and make sure there are no hidden issues you hadn't detected. See below for a suggestion of the easiest way to check out other people's topic branches.

  • Now you are ready to ask for your code to be reviewed and accepted.

    • Open your web browser to your GitHub repo for your fork at https://github.com/youruserid/Xastir.git.

    • Using the pull-down menu, select your feature branch name.

    • To the right, you'll see a button marked "Pull request." Click it to begin the process of creating an automated request to pull your code into the main repo. Fill out all of the form and create a pull request.

    • A member of the Xastir project will review your changes and comment on the pull request. If the changes are straightforward, your request may be accepted directly, or you may be requested to make further changes.

    • If you need to add more commits to address concerns brought up in the review of your pull request, just make them on your topic branch and push them again:

      git checkout <topic branch>
      <edit your files>
      git add <files>
      git commit
      git push
      

      Since you have already associated your topic branch with your forked remote in a previous step, it is no longer necessary to say "-u origin branchname" here.

    • If this goes on for very long, it could come to pass that master has changed again. If so, you may need to rebase and force-push your topic branch. Ideally, you should endeavor to make your pull requests as easy to test and review as possible, so that it doesn't take forever for developers to get around to testing them and merging them.

  There are lots of guidelines out there about how to make good pull requests. Please read https://github.com/blog/1943-how-to-write-the-perfect-pull-request for one such article.

  There is also a pretty nice tutorial on how to do your first pull request at https://www.thinkful.com/learn/github-pull-request-tutorial/

Git Commit Message Format

Git commit messages need to be in a certain format to make the best use of the "git log" commands. In particular the first line needs to be 50 chars or less, then a BLANK LINE, then a detailed commit message. See this link for more info: http://chris.beams.io/posts/git-commit/

Checking out other people's work

It was mentioned above that sometimes it is a good practice to ask other people to check out your code changes before a pull request is opened. This section contains some simple ways for Xastir users and developers to check out code in other people's repos with a minimum of fuss.

Say user "sumgai" has a topic branch named "sumnufeetyur" in a fork of Xastir at "https://github.com/sumgai/Xastir.git". You want to pull those changes and test them out. This can always be done just by cloning the entire fork, but that is not necessary, since most of the fork is a straight copy of the official repo. You can instead just grab sumgai's changes:

• I'm assuming you're already checked out from the master branch, but let's make sure:

  git checkout master
  

• In your regular Xastir clone directory, create a new branch to hold sumgai's work, and switch to it:

  git checkout -b sumgai-sumnufeetyur
  

  When you do this, all you've done so far is to create a new name for a copy of master.

• Now pull sumgai's branch into yours:

  git pull https://github.com/sumgai/Xastir.git sumnufeetuyr
  

  Your sumgai-sumnufeetyur branch will now match sumgai's sumnufeetur branch exactly. This does generally work best if sumgai has kept his branch rebased off of master, which is why we recommend that approach.

• You can now build the code and test it as usual.

• When you're done testing sumgai's code, you can go back to the unmodified Xastir just by doing "git checkout master," and rebuilding the code. If you no longer want to keep a copy of sumgai's work around, you can delete the branch with

  git branch -D sumgai-sumnufeetyur
  

Note to developers: The process of doing this checkout of others' branches is exactly what GitHub recommends as the first steps to resolving pull requests manually through the CLI instead of through github's web interface.

Debugging hints

Xastir is a multi-threaded and multi-process application. It uses both threads and forks to do it's work. You must have a debugger that is capable of following these kinds of twists and turns in a program. Many older versions cannot.

Old notes on using GDB with Xastir

The notes in this section were taken from an old email thread and were written by Tom Russo

According to everything I can find about GDB, debugging of multithreaded apps has been supported in gdb for some time, and are certainly supported in gdb 6.x. For the last couple days I've been running xastir inside gdb instead of at the command prompt --- perhaps I won't keep forgetting to start it with -t now, and when it crashes I'll be where I need to be.

This is possibly an option for you, too, if you're seeing segfaults frequently enough and can't solve the core file question. Try this:

gdb /usr/local/bin/xastir
> run -t

The ">" above is a gdb prompt --- don't type it!

When it crashes, it'll pop you right out into the debugger, whether a core file was created or not. You could then view the active threads:

info threads

and get a stack trace of where the crash happened:

where

You could also probably list the code near where the crash happened:

list

If you send the output of those three commands to the xastir-dev list then it might help us narrow down the causes.

Other old debugging notes

This section was also taken from an old email chain, and was written by Curt Mills

Note that the meaning of the "-t" command-line flag has been reversed [Ed. Note: from what it was in earlier days of Xastir]. "xastir -?" should show the change once you compile it. This means that we'll do core dumps by default upon segfault instead of using the internal Xastir segfault handler. We've also re-enabled the "-g" compile option for GCC so that debugging information will remain embedded in the executable (unless you strip it). This should aid the development team to debug problems.

Also, I cannot find anything in man bash that talks about core dumps nor segmentation faults.

Seems like some stuff we're just supposed to know. How we're supposed to know I don't know either... ;-)

Perhaps that last bit about SUID/SGID might be a clue: There are often exceptions to the rules for SUID/SGID programs. Try not setting Xastir SUID (if you're not using AX.25 kernel networking ports that is) to see if you get a core file. Can you send a SIGSEGV to the running process and make it dump? I just tried this and I'm not getting a core file either.

Ah, I see in the "man bash" page:

ulimit
    -a  All current limits are reported

This gives me:

core file size        (blocks, -c) 0
data seg size         (kbytes, -d) unlimited
file size             (blocks, -f) unlimited
max locked memory     (kbytes, -l) 32
max memory size       (kbytes, -m) unlimited
open files                    (-n) 1024
pipe size          (512 bytes, -p) 8
stack size            (kbytes, -s) unlimited
cpu time             (seconds, -t) unlimited
max user processes            (-u) 6139
virtual memory        (kbytes, -v) unlimited

So... Looks like I need to set "ulimit -c" and try again:

ulimit -c unlimited

Now when I do "kill -11 " I get this:

[1]+  Segmentation fault      (core dumped) xastir

and this:

-rw-------   1 archer users 12320768 2006-02-02 09:31 core.7586

I just added "ulimit -c unlimited" to my .profile. For what it's worth, if Xastir has SUID permission bit set (4755) I don't get a core dump, but if it is reset I do (0755).

I can invoke ddd like this (it uses gdb under the hood):

ddd /usr/local/bin/xastir core.7586 &

or gdb like this:

gdb -c core.7586 /usr/local/bin/xastir

Once you have the program and core file loaded into the debugger you can display a backtrace to see where the program died. In the case of ddd, it's Status->Backtrace, then you click on one of the entries to make the source code window display the exact location.

Another good debugger to try is "UPS".

Another note about core files: Sometimes they get written where you don't expect. I just had one appear in ~/.xastir/tmp, so if you think you should have a core file and can't find it, try:

find . -type f | grep core

The core file may be written to a directory that Xastir is currently in, instead of where you started Xastir from.

Customized debugging builds

Sometimes it is helpful to build xastir with specialized compiler options to aid in debugging. For example, if you're trying to hunt down elusive segfaults, and you're using GCC, it might be wise to build with "-O -g -fno-inline" to prevent the compiler from optimizing quite so vigorously; aggressive optimization can sometimes lead to the debugger saying the code died on one line when in fact it's happening somewhere else.

To build with custom CFLAGS like this, just tell configure what you want CFLAGS to be:

mkdir -p build
cd build
../configure CFLAGS="-O -g -fno-inline"

Naturally, unless you're using build directories separate from the source directory (see below under "Segregating specialized builds"), you need to build every file after changing configure like this, so do a make clean before building:

make clean
make 
make install

Remember not to "make install-strip" when trying to do debugging builds, or your core files will not have debugging symbols in them and it will be harder to get useful information out of the debugger.

Segregating specialized builds

The automake/autoconf setup of xastir makes it easy to maintain several different builds of the code without having to clean out the directory and rebuild every time. One does this with "build directories" and executable suffixes.

To use this capability, make sure you're starting with a completely clean source directory. In the directory where you normally do your "git pull", do a make distclean. This will remove anything that configure created as well as anything that make created. From this point forward, you don't build xastir in the source code directory anymore.

Make an empty directory somewhere --- this will be your build directory.
I put my build directories in parallel with the source code directory. So my tree looks like this:

XASTIR-DEV
 |
 +----/Xastir (source directory)
 |
 +---/build-normal
 |
 +---/build-debug

and so on. Some developers put their build directories inside the Xastir tree instead. It doesn't matter, but does change how you invoke configure (you have to use the correct relative path to configure below).

So I would do:

cd XASTIR-DEV
mkdir -p build-normal

In the build directory, you run configure using the path to the configure script:

cd build-normal
../Xastir/configure
make
make install

The configure script uses the path that you gave when you ran it to figure out where to find the source code.

The beauty of this is you can make a second build without doing a make clean:

cd XASTIR-DEV
mkdir -p build-debug
cd build-debug
../Xastir/configure --program-suffix="-debug" CFLAGS="-O -g -fno-inline"
make && sudo  make install

This will build a second binary called "xastir-debug" and install it, but because you've done the build in a separate directory, your normal compile is untouched.

cd ~/XASTIR-DEV/xastir
git pull
cd ../build-normal
make && sudo make install
cd ../build-debug
make && sudo make install

will update both of your builds.

I also use this technique to share a single xastir source tree over NFS, building the code for multiple operating systems in separate build directories.

(log in to CYGWIN machine, mount NFS directory)
cd /mounted/directory/XASTIR-DEV
mkdir -p build-cygnus
../Xastir/configure
make && make install

It can also be used to maintain specialized configurations, for example a build with "rtree" disabled, a build with map caching disabled, etc. This is a good development trick to keep yourself honest --- make sure you can still build all your custom builds when you've done a large hacking run, and want to check if you have broken things inside ifdefs. Doing that without build directories requires a huge number of configure/make/make distclean cycles.

More?

Anything else? Let's hear about what's still confusing or needs to be expanded in this document. Thanks!

APRS(tm) is a Trademark of Bob Bruninga

Copyright (C) 2000-2023 The Xastir Group