Web   ·   Wiki   ·   Activities   ·   Blog   ·   Lists   ·   Chat   ·   Meeting   ·   Bugs   ·   Git   ·   Translate   ·   Archive   ·   People   ·   Donate
summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README66
-rw-r--r--docs/rationale.txt20
2 files changed, 49 insertions, 37 deletions
diff --git a/README b/README
index ffae342..5c3eb8e 100644
--- a/README
+++ b/README
@@ -23,34 +23,22 @@ Run the commands
That should be all you need to have sugar running!
-= Developing =
+= Developing and contributing =
-You can find all the sources in sugar-build/source. Before running any module
-build command make sure to be inside a shell, so that the environment is
-properly setup. For example if you wanted to make changes to the sugar module
-you could
+First of all enter the sugar-build shell, this will ensure you have the right environment and will provide a few useful extra commands.
make shell
- cd source/sugar
- make install
-
-= Commands reference =
-make build Build everything.
-make run Run sugar.
-make build-[module] Build a single module.
-make clean Delete build artifacts and sources.
-make bug-report Generate a bug report.
-make shell Open a shell with proper build environment.
+You can find all the sources in sugar-build/source. Enter the desired module
+directory and apply the modifications you desire. To test them out, you need to install the new code and start sugar
-= Environment variables =
+ make install
+ start-sugar
-SUGAR_OUTPUT
+Finally, when you have something worth contributing to the community, you should
+send patches to the development mailing list. First of all commit all of your changes to git. Now to send the patches you just run
-Sugar does not run properly on multiple video outputs, so we need to select one
-and turn off the others. By default we select the first output listed by RandR.
-You can set this variable to override that with any other of the connected
-outputs reported by xrandr command, for example VGA1 if you have an external monitor.
+ send-patches
= Report bugs =
@@ -60,23 +48,27 @@ To generate bug report information
I expect a lot of tweaks will be necessary before this is stable. In the future distributions upgrades will also be problematic. We need the build to work out of the box 99% of the time for everyone, so if stuff breaks don't please don't be shy and always report a bug (patches are appreciated of course but not required). If you install an activity and it doesn't work, that might also be a sugar-build bug, in doubt just report it.
-= Rationale =
+= Reference =
-== The current situation ==
+== Makefile targets reference ==
-* We need more people to hack on the core sugar modules. A lot of maintenance is necessary and so many features that are a fundamental part of the initial vision are still unimplemented.
-* Building sugar is currently too complicated and unrealiable. While this is just an annoyance for an experienced hacker, it can a blocker for newcomers. If they can't even get the build to work they are likely to give up and never contribute.
-* It is a difficult problem to solve because we are depending on system components that, while having reasonable ABI policies, are moving very fast (recently with gobject-introspection and gtk3). The number and the level of our dependencies is also much higher than the average project.
-* It's not just about building and running glucose. A good development environment needs to include all the system components activities are allowed to expect.
-* Unrealiability brings more unrealiablity. Build breakages are apparently going unnoticed for several days. I suspect part of the reason is that people just expect things to be broken and deal with it, without reporting or fixing the issues for everyone.
+make build Build everything.
+make run Run sugar.
+make build-[module] Build a single module.
+make clean Delete build artifacts and sources.
+make bug-report Generate a bug report.
+make shell Open a shell with proper build environment.
+
+== Shell commands reference ==
-== How sugar-build tries to improve the situation ==
+start-sugar Start sugar.
+send-patches Send local commits as patches for review.
-* Rather then trying to adapt to the underlining system, it ensures we have a consistent system on all the distributions we support, so that the same identical build process works on all of them. The downside is obvious, we can't expect to work on old distributions. But I think that's a price we can pay for easier maintenance and especially for higher reliability. It's better to support only a few distributions and work flawlessly 99% of the time on the time, then promise support for everything but never work realiably.
-* To verify that all the system components we need are installed we use cross-distribution checks. Though to make life easier for developers we map these to distribution-specific packages and install all of them automatically before starting to build.
-* We only build master of the sugar modules. That's what we want developers to work with. The less build configurations we need to maintain the more likely they are to be realiable. For the same reason we only support the most recent version of a distribution.
-* We build only a couple of essential activities, browse and terminal, to improve the initial develop experience. The rest can be downloaded from activities.sugarlabs.org and they should work because we are ensuring consistent system dependencies.
-* We are using jhbuild internally to keep the amount of custom code to the minimum, but we are not exposing it in the build commands, which are a just few make targets. jhbuild is very flexible but too complicated for us. People should be able to contribute to large parts of the sugar code base without much linux or GNOME experience.
-* Ideally we would only build sugar modules and depend on distributions for everything else. And I hope that's what we will do at some point in the future. Unfortunately in the current development cycle we will need a few components that are not yet packaged, not even written or upstreamed. I believe we can reduce the impact on realiability at the minimum by building only modules that are absolutely required and by checking out a specific commit rather than master. We don't want to get new code from upstream without first verifying that it works well on all the distributions we support. The same is true for jhbuild itself.
-* To ensure reliability of the build scripts and of the sugar code itself, we are going to setup buildbot slaves for all the supported distributions. They will notify the irc channel and perhaps the committers when a build breaks. When it happens I think fixing it should be everyone top priority. Ideally we would also improve our review process so that no code is committed before it has gone through buildbot, gerrit works very well for that but there might be less invasive ways to do it. Regardless of the exact process and tools, patches that add new dependencies to the codebase should come with a corresponding sugar-build patch. Nothing that is pushed should break the buildbots.
-* Ensuring the build works is an important first step. Though integration tests, even if just to verify that stuff actually run, will go a much longer way.
+== Environment variables ==
+
+SUGAR_OUTPUT
+
+Sugar does not run properly on multiple video outputs, so we need to select one
+and turn off the others. By default we select the first output listed by RandR.
+You can set this variable to override that with any other of the connected
+outputs reported by xrandr command, for example VGA1 if you have an external monitor.
diff --git a/docs/rationale.txt b/docs/rationale.txt
new file mode 100644
index 0000000..3c8d059
--- /dev/null
+++ b/docs/rationale.txt
@@ -0,0 +1,20 @@
+= Rationale =
+
+== The current situation ==
+
+* We need more people to hack on the core sugar modules. A lot of maintenance is necessary and so many features that are a fundamental part of the initial vision are still unimplemented.
+* Building sugar is currently too complicated and unrealiable. While this is just an annoyance for an experienced hacker, it can a blocker for newcomers. If they can't even get the build to work they are likely to give up and never contribute.
+* It is a difficult problem to solve because we are depending on system components that, while having reasonable ABI policies, are moving very fast (recently with gobject-introspection and gtk3). The number and the level of our dependencies is also much higher than the average project.
+* It's not just about building and running glucose. A good development environment needs to include all the system components activities are allowed to expect.
+* Unrealiability brings more unrealiablity. Build breakages are apparently going unnoticed for several days. I suspect part of the reason is that people just expect things to be broken and deal with it, without reporting or fixing the issues for everyone.
+
+== How sugar-build tries to improve the situation ==
+
+* Rather then trying to adapt to the underlining system, it ensures we have a consistent system on all the distributions we support, so that the same identical build process works on all of them. The downside is obvious, we can't expect to work on old distributions. But I think that's a price we can pay for easier maintenance and especially for higher reliability. It's better to support only a few distributions and work flawlessly 99% of the time on the time, then promise support for everything but never work realiably.
+* To verify that all the system components we need are installed we use cross-distribution checks. Though to make life easier for developers we map these to distribution-specific packages and install all of them automatically before starting to build.
+* We only build master of the sugar modules. That's what we want developers to work with. The less build configurations we need to maintain the more likely they are to be realiable. For the same reason we only support the most recent version of a distribution.
+* We build only a couple of essential activities, browse and terminal, to improve the initial develop experience. The rest can be downloaded from activities.sugarlabs.org and they should work because we are ensuring consistent system dependencies.
+* We are using jhbuild internally to keep the amount of custom code to the minimum, but we are not exposing it in the build commands, which are a just few make targets. jhbuild is very flexible but too complicated for us. People should be able to contribute to large parts of the sugar code base without much linux or GNOME experience.
+* Ideally we would only build sugar modules and depend on distributions for everything else. And I hope that's what we will do at some point in the future. Unfortunately in the current development cycle we will need a few components that are not yet packaged, not even written or upstreamed. I believe we can reduce the impact on realiability at the minimum by building only modules that are absolutely required and by checking out a specific commit rather than master. We don't want to get new code from upstream without first verifying that it works well on all the distributions we support. The same is true for jhbuild itself.
+* To ensure reliability of the build scripts and of the sugar code itself, we are going to setup buildbot slaves for all the supported distributions. They will notify the irc channel and perhaps the committers when a build breaks. When it happens I think fixing it should be everyone top priority. Ideally we would also improve our review process so that no code is committed before it has gone through buildbot, gerrit works very well for that but there might be less invasive ways to do it. Regardless of the exact process and tools, patches that add new dependencies to the codebase should come with a corresponding sugar-build patch. Nothing that is pushed should break the buildbots.
+* Ensuring the build works is an important first step. Though integration tests, even if just to verify that stuff actually run, will go a much longer way.