-
Notifications
You must be signed in to change notification settings - Fork 237
Reporting Bugs and Feature Requests
Please do not create an issue or ask for help in other channels until you have read carefully this entire wiki page.
If you created an issue and it was closed with only a link to this page, please read this page carefully, because the person who closed your issue almost certainly believes that your issue does not follow the rules described here.
Unison does have a history of being helpful to people who take the time to ask for help in the right channels and follow the guidance in this page. However, there are a only small number of people doing so, and the guidelines here are meant to maintain that willingness.
Unison's product is the source code. A packaging system having an old version is not a bug in Unison. The CI-provided binaries exist for Continuous Integration and are useful for users as a side benefit. Therefore, the CI binaries not working on a particular operating system is not a Unison bug. (In general, binaries should be provided by packaging systems.)
Generally, problems are fixed on the git master branch, and from time to time a new release is made. From the project's viewpoint, old releases are obsolete, and bugs in them are no longer relevant. While the license gives you the right to run old code, no one is interested in helping with that -- advice is essentially always to upgrade.
If you are running an old version of Unison because you choose to run an LTS release, because someone else controls the computer on which it is running, or because your packaging system or operating system has an old version, that is something to be addressed with those parties, not with the Unison project.
The issue tracker is for bug reports and (limited) enhancement requests. Specifically, this means that questions and requests for help are not appropriate as issues; those should be directed to unison-users (or unison-hackers if the discussion requires reading the source code). Questions in the issue tracker will be summarily closed without answers.
The unison project does not provide support for old versions. As of 2022-04, only 2.52.0 and newer are considered new enough to be allowed in the issue tracker. If you are running an older version, especially 2.48, please upgrade before asking for help. See https://github.com/bcpierce00/unison/wiki/Downloading-Unison for how to get precompiled binaries for a limited set of platforms. The unison-users list is the appropriate place for help upgrading.
This guidance to update applies even if your operating system provides an older version. The group of people contributing to unison maintenance is not responsible for how packaging systems (including GNU/Linux distributions) update unison, even though some of them help with some systems. Please address issues such as "FooOS 42 has unison 2.48" to FooOS.
First, look in the manual, and the FAQ section of the old website at https://alliance.seas.upenn.edu/~bcpierce/wiki/index.php. Lots of questions are answered there.
Next, try running Unison with the "-debug all" command line option. This will cause Unison to generate a detailed trace of what it's doing, which may help pinpoint where the problem is occurring.
Try to reduce the complexity of what you are doing. Sync locally even if that's not what you ultimately want. Turn off the watcher. If you can succeed at that, add things back one at a time.
There may be a bug report already that is similar. It might contain a workaround. You might be able to provide additional details, such as if you find a way to avoid or trigger the bug. See the github bugtracker
If the previous steps didn't clarify matters, try sending an email describing your problem to the users' list. (Make sure you subscribe first, so that you'll see people's responses in case they reply only to the list!)
Please include the version of Unison you are using (unison -version), the ocaml version you compiled with, the OS type you are running it on, the version of the OS, the CPU type, a record of what gets printed when the -debug all option is included, and as much information as you can about what went wrong. Be sure to include version information for both machines if syncing non-locally.
The Github issue tracker has open tickets for bugs, and for enhancement requests. If you can clearly articulate that the current version of unison is behaving incorrectly, you are welcome to file a bug report. Bug reports must include the version information described in the previous section.
Note that bugs must be against a recent version, often the most recent version. Even if you report a bug against 2.51.5 in 2022-04, you will likely be asked to update and retest.
The language should be along the lines of "unison does this wrong. I did X and should have gotten Y but Z happened". If you are about to write "I don't understand how to do X" or "If I did Y would it work", that is a clue that your message belongs on the users list and is not a bug report. The bug tracker is not a forum, and questions in the bug tracker will be summarily closed.
Your issue, if not closed, will probably get labels with the maintainer's assessment of importance, difficulty, etc. Do not worry about these decisions; bugs get fixed when someone submits a quality PR, and there is no team working on your high-priority bug.
Please understand that there are not a lot of people spending a lot of time maintaining unison, and that therefore requests for non-trivial features that would be useful to a tiny number of people are not necessarily a good tradeoff of the usefulness of the request vs the cognitive load of open tickets. Therefore, such speculative feature tickets may be closed. That said, well-articulated feature requests that are likely of interest to at least some others are welcome.
Please phrase feature requests as "Add ability to do X" or something along those lines. Explain precisely what the new behavior is. Discuss alternative approaches and why the proposed behavior is correct. If you are unclear on what is desired, pick one of the mailinglists to discuss and crystallize first.