Add a README.md.

This file explains how we work with upstream initscripts from fedora
and how to use it to generate the Mageia initscripts .spec

1 files changed, 96 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..cfa516ef
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# Mageia's Init Scripts
+
+This is a fork of the Fedora Init Script package which currently lives over at
+[Fedora Hosted](https://git.fedorahosted.org/cgit/initscripts.git/).
+
+----
+## History
+
+This repository was recreated from the original Mandriva initscripts by Mageia (and formerly Mandriva) contributor Colin Guthrie to help better manage merging of upstream Fedora changes.
+
+Many of the changes made relate to translations which are now hideously out of date, and various networking tweaks and various things to improve boot speed (aka SpeedBoot) from before the times of [systemd](http://www.freedesktop.org/wiki/Software/systemd/). Several of these changes have now been removed again as they are obsolete.
+
+The repository does not contain full history (although that was an original intention) as the benefits of this vs. the effort involved are somewhat questionable.
+
+----
+## How to Use
+
+In order to use this repository usefully in Mageia, you have to follow a few rules for cloning that are somewhat non standard due to this being a "fork".
+
+### Cloning
+
+To clone, you should first clone from upstream Fedora first:
+
+    $ git clone git://git.fedorahosted.org/initscripts
+
+Once it's cloned, you need to then add a remote for *our* fork:
+
+    $ cd initscripts
+    $ git remote add mga ssh://git@git.mageia.org/software/forks/initscripts
+
+And once you have that cloned, you should setup a local tracking branch for our main development branch which is named after the current stable distro version + 1:
+
+    $ git checkout -t mga/distro/mga4
+
+Note: It is strongly recommended to install the *git-prompt* package to see which branch you are currently using.
+
+### Merging with upstream
+
+When upstream release a new version, we will periodically merge in their changes. Due to the deviations over the years this is sometimes a rather complex task and not for the faint hearted! That said, some of our modifications really are out of date now and could, in all honesty, be dropped in favour of the upstream version - probably worth keeping this in mind when doing a complex merge and perhaps discussing with others on the Cauldron mailing list.
+
+#### Updating upstream
+
+You need to update from upstream so you can do:
+
+    $ git checkout master
+    $ git pull
+
+This should bring in new code from fedora.
+
+You can then push this to us quite happily:
+
+    $ git push mga master
+    $ git push mga --tags
+
+**Important Note**: Keep in mind that our master branch should just be a mirror of Fedora's. We should not put any of our own changes on this branch.
+
+#### Merging
+
+We try to stick to merging only upstream tags. To do this we would simply do:
+
+    $ git merge initscripts-9.48-1
+
+You then have the fun job of fixing the (no doubt) numerous conflicts!
+
+When you are ready to commit, please just use the default commit message git generates automatically for a merge commit. It will automatically list any files that had merge conflicts.
+
+If you have decided to revert a file to the upstream version in your commit, please mention this in the commit message at the end.
+
+### Packaging changes
+
+#### Super patch
+Periodically, we will generate a **super patch** containing all our changes. This patch is generated from the upstream tag of the tarball we are using and our current HEAD. It is generated via a command similar to:
+
+    $ git diff initscripts-9.48-1..mga/distro/mga4 | xz >initscripts-mgaconf.patch.xz
+
+Note that the *upstream* branch for *distro/mga4* is used (as it's prefixed with the remote name *mga/*). This is because you should be careful to only generate the super patch from changes you **have already pushed**. If you do not do this other contributors may not be able to verify your patch and some commits may even be lost. You have been warned!
+
+Once you have generated the super patch you should note the sha1 of the the current head and include it as a comment in the initscripts.spec file.
+
+#### Incremental patches
+
+In order to cut down on the number of times we regenerate the super patch we will usually package incremental patches to fix issues as they occur. These patches should be committed to the distro/mgaN branch and pushed. Once they have been pushed they should not be edited and any further changes should be made as new patches.
+
+To generate the incremental patches take the sha1 sum as noted in the initscripts.spec and run the following command:
+
+    $ git format-patch --start-number 100 SHA1..mga/distro/mga4
+
+Note that I've used the full remote branch name here too which means changes have to be pushed first, but if you are creating a package for testing you can of course just use your local branch.
+
+### Pushing changes
+
+When you are happy with your changes you should push them. To do this type:
+
+    $ git push mga distro/mga4
+
+You can adjust this accordingly to match various git config settings as you see fit.