CONTRIBUTING.md (4766B)
1 # Introduction 2 3 This file describes many aspects of contributing to Unison beyond 4 testing and bug reporting. 5 6 ## Maintenance status 7 8 Unison has no paid contributors. There are currently about 0.1 FTE 9 across 2 people regularly contributing. There are no plans for 10 significant feature development. 11 12 Help is welcome, and the details are below. 13 14 ## unison-hackers 15 16 Discussion of the source code, proposed changes, etc. is most 17 appropriate on the `unison-hackers@` mailinglist. (See 18 https://github.com/bcpierce00/unison/wiki/Mailing-Lists). 19 20 ## Development and Submitting Proposed Changes 21 22 The file `src/ROADMAP.txt` has a very basic orientation. 23 24 Proposed code changes are also welcome (as pull requests). For 25 significant changes, an enhancement request or bug report is likely in 26 order to provide the proposed semantics ahead of time. For changes 27 that are likely to be nearly-universally viewed as clearly desired, 28 that might be enough. Others should be discussed on unison-hackers. 29 30 Proposed changes should change documentation in concert with code, and 31 should pass CI. 32 33 Expect comments and requests for adjustments. Unison typically 34 expects contributors to use fixup commits for tweaks and rebase so 35 that there is a clean set of commits from a recent point on master. 36 37 ## Licensing 38 39 Unison operates under the widely-used "inbound=outbound" contribution 40 license process. Therefore, all contributions to Unison must be 41 licensed under the project's license, currently GPLv3 (unless a file 42 under a different license is being modified). New files of 43 significance must have a copyright statement and grant permission to 44 copy under the project's license. Significant changes should include 45 copyright statements and/or add authors. Submitting a pull request or 46 posting a contribution on a mailinglist is an assertion that the 47 submitter has the authority to license their changes under the 48 project's license. (This paragraph is intended to summarize the 49 normal conventions, and is not intended to create any new norms. See 50 https://sfconservancy.org/blog/2014/jun/09/do-not-need-cla/ for a 51 longer discussion.) 52 53 ## CI 54 55 Github requires maintainer approval for new contributors to be able to 56 run workflows, and this is routinely granted. Thus, CI should run on 57 your PR after a maintainer has had a chance to take an initial look. 58 59 ## Strings 60 61 Running `make docs` will regenerate `src/strings.ml`. This change 62 should be in a commit by itself with commit message "Regen 63 strings.ml". 64 65 ## Build systems 66 67 Unison has both make and dune. Changes should adjust both, and CI 68 will check that. 69 70 ## Format breaks 71 72 Since 2.52, we attempt to have back compat for archive format and wire 73 format. There is feature negotiation for extensions; see 74 src/FEATURES.md and `src/features.mli` for more information. 75 76 ## Portability 77 78 Unison runs on *BSD, GNU/Linux, macOS, Solaris/illumos and Windows. 79 Generally Unison aims to use interfaces specified by POSIX, and views 80 non-POSIX systems as deficient and in need of workarounds. In 81 practice this means Windows :-) 82 83 Sometimes it is necessary to use beyond-POSIX interfaces, but this 84 should be done with care. An example might be optional support of 85 features on some systems, where other systems do not implement the 86 necessary interfaces. However, if there are semantically similar 87 interfaces, all such systems should be supported, and the code should 88 be structured to admit additional implementations. Generally these 89 adaptations will be in C code, hiding the portability issues from our 90 ocaml code base. Discussion on `unison-hackers@` is almost certainly 91 warranted. 92 93 Unison has a TUI (text/CLI) which requires very little beyond ocaml. 94 There are two GUIs, one with GTK3 and one for mac. Generally we try 95 to be evenhanded with features, but leaving the mac proprietary GUI 96 behind is not prohibited. 97 98 ## Accommodation of old systems 99 100 Keeping Unison running on old systems can cause accumulation of crufty 101 workarounds. Unison is very old, and it likely has accommodations for 102 90s problems. 103 104 Generally, we aim to keep it working on even very old systems as long 105 as there is no cost in technical debt. However, we are also trying to 106 reduce the code size by removing workarounds for systems that are no 107 longer in use. 108 109 Unison's working definition of a system that is new enough to justify 110 a workaround is one of: 111 - system is currently receiving maintenance by its upstream 112 - system is Free Software, not LTS, and is no more than 3 years 113 beyond the end of maintenance 114 115 Even for systems that are not new enough, we will likely apply a 116 cost/benefit analysis to pruning. For example, workarounds for 117 Windows 7 with minor carrying cost will likely not be removed in 2023, 118 but workarounds for Windows NT are unlikely to be kept.