From 3d2e9b72d0a65d2d31f72f32d92c43b442767948 Mon Sep 17 00:00:00 2001 From: Jon Lund Steffensen Date: Mon, 14 Aug 2017 15:06:09 -0700 Subject: Rename HACKING.md to CONTRIBUTING.md --- CONTRIBUTING.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ HACKING | 1 - HACKING.md | 169 -------------------------------------------------------- Makefile.am | 2 +- README.md | 2 +- 5 files changed, 171 insertions(+), 172 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 120000 HACKING delete mode 100644 HACKING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c41b0e3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,169 @@ + +Build from repository +--------------------- + +``` shell +$ ./bootstrap +$ ./configure +``` + +The bootstrap script will use autotools to set up the build environment +and create the `configure` script. + +Use `./configure --help` for options. Use `--prefix` to make an install in +your home directory. This is necessary to test python scripts. The systemd +user unit directory should be set to avoid writing to the system location. + +Systemd will look for the unit files in `~/.config/systemd/user` so this +directory can be used as a target if the unit files will be used. Otherwise +the location can be set to `no` to disable the systemd files. + +Example: + +``` shell +$ ./configure --prefix=$HOME/redshift/root \ + --with-systemduserunitdir=$HOME/.config/systemd/user +``` + +Now, build the files: + +``` shell +$ make +``` + +The main redshift program can be run at this point. To install to the +prefix directory run: + +``` shell +$ make install +``` + +You can now run the python script. Example: + +``` shell +$ $HOME/redshift/root/bin/redshift-gtk +``` + +Dependencies +------------ + +* autotools, gettext +* intltool, libtool +* libdrm (Optional, for DRM support) +* libxcb, libxcb-randr (Optional, for RandR support) +* libX11, libXxf86vm (Optional, for VidMode support) +* geoclue (Optional, for geoclue support) + +* python3, pygobject, pyxdg (Optional, for GUI support) +* appindicator (Optional, for Ubuntu-style GUI status icon) + +Ubuntu users will find all these dependencies in the packages listed in ``.travis.yml``. + +Coding style +------------ + +Redshift follows roughly the Linux coding style +. Some specific rules to +note are: + +* Lines should not be much longer than 80 chars but this is not strictly + enforced. If lines are much longer than this the code could likely be improved + by moving some parts to a smaller function. +* All structures are typedef'ed. +* Avoid Yoda conditions; they make the logic unnecessarily hard to comprehend. +* Avoid multiline if-statements without braces; either use a single line or add + the braces. +* Use only C-style comments (`/* */`). + + +Creating a pull request +----------------------- + +1. Create a topic branch for your specific changes. You can base this off the + master branch or a specific version tag if you prefer (`git co -b topic master`). +2. Create a commit for each logical change on the topic branch. The commit log + must contain a one line description (max 80 chars). If you cannot describe + the commit in 80 characters you should probably split it up into multiple + commits. The first line can be followed by a blank line and a longer + description (split lines at 80 chars) for more complex commits. If the commit + fixes a known issue, mention the issue number in the first line (`Fix #11: + ...`). +3. The topic branch itself should tackle one problem. Feel free to create many + topic branches and pull requests if you have many different patches. Putting + them into one branch makes it harder to review the code. +4. Push the topic branch to Github, find it on github.com and create a pull + request to the master branch. If you are making a bug fix for a specific + release you can create a pull request to the release branch instead + (e.g. `release-1.9`). +5. Discussion will ensue. If you are not prepared to partake in the discussion + or further improve your patch for inclusion, please say so and someone else + may be able to take on responsibility for your patch. Otherwise we will + assume that you will be open to critisism and suggestions for improvements + and that you will take responsibility for further improving the patch. You + can add further commits to your topic branch and they will automatically be + added to the pull request when you push them to Github. +6. You may be asked to rebase the patch on the master branch if your patch + conflicts with recent changes to the master branch. However, if there is no + conflict, there is no reason to rebase. Please do not merge the master back + into your topic branch as that will convolute the history unnecessarily. +7. Finally, when your patch has been refined, you may be asked to squash small + commits into larger commits. This is simply so that the project history is + clean and easy to follow. Remember that each commit should be able to stand + on its own, be able to compile and function normally. Commits that fix a + small error or adds a few comments to a previous commit should normally just + be squashed into that larger commit. + +If you want to learn more about the Git branching model that we use please see + but note that we use +the `master` branch as `develop`. + + +Creating a new release +---------------------- + +1. Select a commit in master to branch from, or if making a bugfix release + use previous release tag as base (e.g. for 1.9.1 use 1.9 as base) +2. Create release branch `release-X.Y` +3. Apply any bugfixes for release +4. Import updated translations from launchpad and commit. Remember to update + `po/LINGUAS` if new languages were added +5. Update version in `configure.ac` and create entry in NEWS +6. Run `make distcheck` +7. Commit and tag release (`vX.Y` or `vX.Y.Z`) +8. Push tag to Github and also upload source dist file to Github + +Also remember to check before release that + +* Windows build is ok +* Build files for distributions are updated + + +Build Fedora RPMs +----------------- + +Run `make dist-xz` and copy the `.tar.xz` file to `~/rpmbuild/SOURCES`. Then run + +``` shell +$ rpmbuild -ba contrib/redshift.spec +``` + +If successful this will place RPMs in `~/rpmbuild/RPMS`. + + +Cross-compile for Windows +------------------------- + +Install MinGW and run `configure` using the following command line. Use +`i686-w64-mingw32` as host for 32-bit builds. + +``` shell +$ ./configure --disable-drm --disable-randr --disable-vidmode --enable-wingdi \ + --disable-geoclue --disable-gui --disable-ubuntu \ + --host=x86_64-w64-mingw32 +``` + + +Notes +----- +* verbose flag is (currently) only held in redshift.c; thus, write all + verbose messages there. diff --git a/HACKING b/HACKING deleted file mode 120000 index 36b0b3a..0000000 --- a/HACKING +++ /dev/null @@ -1 +0,0 @@ -HACKING.md \ No newline at end of file diff --git a/HACKING.md b/HACKING.md deleted file mode 100644 index c41b0e3..0000000 --- a/HACKING.md +++ /dev/null @@ -1,169 +0,0 @@ - -Build from repository ---------------------- - -``` shell -$ ./bootstrap -$ ./configure -``` - -The bootstrap script will use autotools to set up the build environment -and create the `configure` script. - -Use `./configure --help` for options. Use `--prefix` to make an install in -your home directory. This is necessary to test python scripts. The systemd -user unit directory should be set to avoid writing to the system location. - -Systemd will look for the unit files in `~/.config/systemd/user` so this -directory can be used as a target if the unit files will be used. Otherwise -the location can be set to `no` to disable the systemd files. - -Example: - -``` shell -$ ./configure --prefix=$HOME/redshift/root \ - --with-systemduserunitdir=$HOME/.config/systemd/user -``` - -Now, build the files: - -``` shell -$ make -``` - -The main redshift program can be run at this point. To install to the -prefix directory run: - -``` shell -$ make install -``` - -You can now run the python script. Example: - -``` shell -$ $HOME/redshift/root/bin/redshift-gtk -``` - -Dependencies ------------- - -* autotools, gettext -* intltool, libtool -* libdrm (Optional, for DRM support) -* libxcb, libxcb-randr (Optional, for RandR support) -* libX11, libXxf86vm (Optional, for VidMode support) -* geoclue (Optional, for geoclue support) - -* python3, pygobject, pyxdg (Optional, for GUI support) -* appindicator (Optional, for Ubuntu-style GUI status icon) - -Ubuntu users will find all these dependencies in the packages listed in ``.travis.yml``. - -Coding style ------------- - -Redshift follows roughly the Linux coding style -. Some specific rules to -note are: - -* Lines should not be much longer than 80 chars but this is not strictly - enforced. If lines are much longer than this the code could likely be improved - by moving some parts to a smaller function. -* All structures are typedef'ed. -* Avoid Yoda conditions; they make the logic unnecessarily hard to comprehend. -* Avoid multiline if-statements without braces; either use a single line or add - the braces. -* Use only C-style comments (`/* */`). - - -Creating a pull request ------------------------ - -1. Create a topic branch for your specific changes. You can base this off the - master branch or a specific version tag if you prefer (`git co -b topic master`). -2. Create a commit for each logical change on the topic branch. The commit log - must contain a one line description (max 80 chars). If you cannot describe - the commit in 80 characters you should probably split it up into multiple - commits. The first line can be followed by a blank line and a longer - description (split lines at 80 chars) for more complex commits. If the commit - fixes a known issue, mention the issue number in the first line (`Fix #11: - ...`). -3. The topic branch itself should tackle one problem. Feel free to create many - topic branches and pull requests if you have many different patches. Putting - them into one branch makes it harder to review the code. -4. Push the topic branch to Github, find it on github.com and create a pull - request to the master branch. If you are making a bug fix for a specific - release you can create a pull request to the release branch instead - (e.g. `release-1.9`). -5. Discussion will ensue. If you are not prepared to partake in the discussion - or further improve your patch for inclusion, please say so and someone else - may be able to take on responsibility for your patch. Otherwise we will - assume that you will be open to critisism and suggestions for improvements - and that you will take responsibility for further improving the patch. You - can add further commits to your topic branch and they will automatically be - added to the pull request when you push them to Github. -6. You may be asked to rebase the patch on the master branch if your patch - conflicts with recent changes to the master branch. However, if there is no - conflict, there is no reason to rebase. Please do not merge the master back - into your topic branch as that will convolute the history unnecessarily. -7. Finally, when your patch has been refined, you may be asked to squash small - commits into larger commits. This is simply so that the project history is - clean and easy to follow. Remember that each commit should be able to stand - on its own, be able to compile and function normally. Commits that fix a - small error or adds a few comments to a previous commit should normally just - be squashed into that larger commit. - -If you want to learn more about the Git branching model that we use please see - but note that we use -the `master` branch as `develop`. - - -Creating a new release ----------------------- - -1. Select a commit in master to branch from, or if making a bugfix release - use previous release tag as base (e.g. for 1.9.1 use 1.9 as base) -2. Create release branch `release-X.Y` -3. Apply any bugfixes for release -4. Import updated translations from launchpad and commit. Remember to update - `po/LINGUAS` if new languages were added -5. Update version in `configure.ac` and create entry in NEWS -6. Run `make distcheck` -7. Commit and tag release (`vX.Y` or `vX.Y.Z`) -8. Push tag to Github and also upload source dist file to Github - -Also remember to check before release that - -* Windows build is ok -* Build files for distributions are updated - - -Build Fedora RPMs ------------------ - -Run `make dist-xz` and copy the `.tar.xz` file to `~/rpmbuild/SOURCES`. Then run - -``` shell -$ rpmbuild -ba contrib/redshift.spec -``` - -If successful this will place RPMs in `~/rpmbuild/RPMS`. - - -Cross-compile for Windows -------------------------- - -Install MinGW and run `configure` using the following command line. Use -`i686-w64-mingw32` as host for 32-bit builds. - -``` shell -$ ./configure --disable-drm --disable-randr --disable-vidmode --enable-wingdi \ - --disable-geoclue --disable-gui --disable-ubuntu \ - --host=x86_64-w64-mingw32 -``` - - -Notes ------ -* verbose flag is (currently) only held in redshift.c; thus, write all - verbose messages there. diff --git a/Makefile.am b/Makefile.am index 1e2f1c8..3f941d6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -9,7 +9,7 @@ DISTCHECK_CONFIGURE_FLAGS = \ UPDATE_ICON_CACHE = gtk-update-icon-cache -f -t $(datadir)/icons/hicolor || : EXTRA_ROOTDOC_FILES = \ - HACKING \ + CONTRIBUTING.md \ DESIGN \ README \ README-colorramp \ diff --git a/README.md b/README.md index 4f9a52a..890732d 100644 --- a/README.md +++ b/README.md @@ -115,4 +115,4 @@ Latest builds from master branch Building from source -------------------- -See the file [HACKING](HACKING.md) for more details on building from source. +See the file [CONTRIBUTING](CONTRIBUTING.md) for more details on building from source. -- cgit v1.2.3-70-g09d2