1<!--- IF THIS DOCUMENT IS UPDATED THEN ALSO UPDATE THE FVWM WEB REPO ---> 2 3Developing for FVWM 4=================== 5 6This document aims to help the developer with the expectations when dealing 7with the FVWM source code. 8 9The FVWM source conforms to the [Linux kernel style 10guide](https://www.kernel.org/doc/Documentation/CodingStyle). 11 12Command Parsing 13=============== 14 15The internal representation of how fvwm parses commands in undergoing a 16rewrite. [Some notes on how fvwm parses commands exists](PARSING.md). 17 18Branch Workflows / Submitting Code Changes 19========================================== 20 21The main FVWM repository treats the `master` branch as stable, in that it's the 22branch which has the most tested code on it, and the branch from which releases 23are made. Formal releases of FVWM are tagged, in the form `x.y.z`, historical 24versions of FVWM are tagged as `version-x_y_z`. Untagged code may well 25accumulate on `master`, which will go to form the next release. 26 27Other branches in the repository will reflect on-going development from core 28fvwm-workers. As such, these branches are often in a state of flux, and likely 29to be rebased against other branches. *NO* code should be based off topic 30branches, unless explicitly agreed with other developers, who might need to 31collaborate. 32 33### Branch naming 34 35Branch names are used to try and indicate the feature, and who is working on 36them. So for example, a topic-branch will be named as: 37 38`initials/rough-description-of-branch` 39 40For example: 41 42`ta/fix-clang-warnings` 43 44denotes that the branch is worked on by someone with the initials `TA` and that 45the branch is about fixing warnings from Clang. 46 47Sometimes, if more than one person is collaborating on a branch, the initials 48prefix might not be needed. 49 50### Updating NEWS 51 52When submitting patches, please also update the NEWS file with relevant 53highlights as to new functionality and/or bug-fixes. For inspiration, GNU 54have a [list](https://www.gnu.org/prep/standards/standards.txt). 55 56### Submitting Pull-requests 57 58External contributions are always welcomed and encouraged. If you're thinking 59of writing a new feature, it is worthwhile posting an email to the 60`fvwm-workers` mailing list to discuss whether it's a good idea, and to check no 61one else is working on that feature. 62 63Those wishing to submit code/bug-fixes should: 64 65* [Fork the FVWM-repository](https://github.com/fvwmorg/fvwm#fork-destination-box) 66* Add the [FVWM-repo](https://github.com/fvwmorg/fvwm.git) as an upstream 67 remote: 68 * `git remote add fvwmorg https://github.com/fvwmorg/fvwm.git && 69 git fetch fvwmorg` 70* Create a topic-branch to house your work; 71* Rebase it against `fvwmorg/master` 72* Push the latest changes to your fork; 73* Open a pull-request 74 75Once a pull-request is opened, an email is sent to the `fvwm-workers` list so we 76can take a look at it. 77 78Alternatively, if pull-requests are not an option, then `git-send-email` can be 79used, sending the relevant patchsets to the `fvwm-workers` mailing list. 80 81### Protected branches and the use of Travis-CI 82 83Pull-requests made will result in the use of Travis-CI being run against the 84branch. This builds the copy of the pushed code in a Ubuntu environment, with 85all the additional libraries FVWM could use, loaded in. Builds are made against 86`gcc` and `clang`, because both those compilers cover slightly different angles 87with respect to compiling. All warnings are treated as errors, and if a build 88does not succeeded, ensure the code is fixed, and pushed back out on the same 89branch. Rebasing is recommended; Travis-CI and Github handle this just fine. 90 91The FVWM repository also treats the `master` branch as protected. This is a 92[GitHub feature](https://help.github.com/articles/about-protected-branches/) 93which means the `master` branch in this case cannot have changes merged into it 94until Travis-CI has verified the builds do not fail. 95 96This has merit since not every developer will be using the same operating 97systems (Linux versus BSD for instance), and that `master` is meant to try and 98be as release-worthy as can be. 99 100**NOTE**: This means that no work can be commited to `master` directly. ALL 101work that needs to appear on `master`---including the release 102process---**MUST** go via a separate topic-branch, with a PR (pull-request). 103Not even fvwmorg owners are an exception to this. 104 105### Merging changes / Pull Requests 106 107The history of `master` should be as linear as possible, therefore when 108merging changes to it the branch(es) in question should be rebased against 109master first of all. This will stop a merge commit from happening. 110 111If using github this process is easy, since the `Merge pull request` button 112has an option to `Rebase and Merge`. This is what should be used. See also 113[the documentation on Github](https://github.com/blog/2243-rebase-and-merge-pull-requests) 114 115If this is manual (which will only work when the Travis-CI checks have 116passed), then: 117 118``` 119git checkout topic/branch 120git rebase origin/master 121git checkout master 122git merge topic/branch 123git push 124``` 125Conventions 126========== 127 128The following tries to list all the conventions that the fvwm developers 129adhere to, either by consensus through discussion, common practice or unspoken 130agreement. It is hopefully useful for the fvwm development newbie. 131 132Programming Languages 133-------------------- 134 135 The following programming languages are allowed: 136 137- ANSI C 138- Perl 139- Portable /bin/sh scripts for examples. 140 141New Code Files 142-------------- 143 144- There are templates for new code files in the fvwm directory. Try to always 145 use them as they provide a clean structure of the header and code files. 146 Please honour the section titles. For example, put all static functions 147 (and only static functions) under the "local functions" section. 148 149- All .c files *must* have 150 151``` 152#include "config.h" 153``` 154 155as the first non-comment line. Otherwise the settings made by the configure 156script may not be used. This can cause random problems. 157 158File Names 159---------- 160 161- The names of the code files in the fvwm directory are in lower case. 162- Files in the libs directory may begin with a capital 'F'. This letter is 163 reserved for wrapper files for third party libraries or modules. For 164 example, FShape is an abstraction of the XShape X server extension and FBidi 165 is a wrapper for the fribidi library. Do not use the 'F' for other 166 purposes. 167 168Copyright Notices 169----------------- 170 171- A copy of the GPL should be at the beginning of all code files (.c) and 172 scripts, but not at the beginning of header files (.h). 173 174Maintaining Man Pages 175--------------------- 176 177- Every feature must be described with all options in the man page. 178 179Creating a release 180================== 181 182Before deciding to make a new release, please check with the `fvwm-workers` 183mailing list that this is the right time to do so. This will give adequate 184warning for other developers to give status updates about any in-flight 185development that's happening which might impact a potential release. 186 187Make sure you have all optional libraries installed. 188 189**NOTE: as `master` is a protected branch, changes made to files during the 190release phase must be done on a separate branch, and not on master directly, 191as pushes to this branch are not allowed until checks have been done on it. 192This means the end result of the release-phase must have these changes issued 193as a pull-request against `master`.** 194 1950. `git checkout master && git pull && git checkout -b release/x.y.z` 196 **Where: `x.y.z` will be the next release**. 1971. Change the dates in configure.ac and fill in the release dates. 1982. Set `ISRELEASED` to `"yes"`. 1993. Change `utils/fvwm-version-str.sh` and include the approrpiate version 200 string. 2014. Commit the results. 2025. Run: `./autogen.sh && make clean` to get the tree into a clean 203 slate. Because this is a release, the source needs compiling. To do 204 that, run: 205 206 ``` 207 make CFLAGS="-g -O2 -Wall -Wpointer-arith -fno-strict-aliasing -Werror" 208 ``` 209 210 Fix all warnings and problems, commit the changes and repeat the previous 211 command until no more warnings occur. 2126. Tag the release: `git tag -a x.y.z` -- where `x.y.z` represents the 213 appropriate version number for the release. 2147. Build and test the release tarballs: 215 216 Run: `make dist` 217 218 If that succeeds, check for `fvwm-x.y.z.tar.gz` in the current working 219 directory. This is the release tarball which will be uploaded to Github. 220 Unpack it to a temporary directory and build it; check the version as well, 221 via: `./fvwm --version`. 2228. Push the tag out: `git push origin x.y.z` -- where `x.y.z` is the specific 223 tag created in step 6. 2249. Set `ISRELEASED` to `"no"` in configure.ac and commit and push that out. 22510. Issue a PR (pull-request) against `master` and mege that in assuming all 226 checks pass. If not, fix the problems, and repeat this step. 22711. Upload the `fvwm-x.y.z.tar.gz` tarball to Github against the tag just 228 pushed. 22912. Update the fvwm web site (see below) 230 231Updating fvwm-web 232================= 233 2341. Ensure you've a checkout of the repository: 235 236 ``` 237 git clone git@github.com:fvwmorg/fvwmorg.github.io.git 238 ``` 2392. Update the `RELEASE` variable in `Makefile` to the desired version which 240 has been released. 2413. Run `make`. This will update all relevant files. 2424. `git commit -a` the result, and push it out. 243