Introduction

Introduction

In the early days of the development of Ampersand, it was a single person's project. Haskell was used as programming language, and the source code was kept on a single PC. Fortunately, things have evolved. Now we have a team, and we use quite a lot of open source tooling to help us along. The downside is that not everybody in the team knows all there is to know about the tooling. The purpose of this guide is to help out. It will also be a great place to start for new team members.

The up to date version of this book is published automatically every time a commit is done to the master branch.

Documentation on actually using Ampersand - e.g. for making and running prototypes (including the ways to install on your computer what it takes to do so) - is in another document, called Ampersand Documentation

Working Principles

  • The Ampersand project produces free open source software, available to everyone.

  • "We" is the Ampersand community as specified on Github. We adhere to our own working principles to the best of our ability.

  • We respect the intellectual contribution of all. We wish to keep it that way by acknowledging intellectual ownership wherever appropriate.

  • We write software for maintainability, to facilitate others to contribute. This implies simplicity and understandability of all software artifacts. It means we document code to be relevant (for new team members), complete (for finding everything you need), and minimal (to save readers some reading effort). It implies we reuse code and strive for orthogonal design.

  • We automate the production of software to the max, to obtain robust and fast deployments and save ourselves repeated work.

  • When in trouble, we write an issue on GitHub. We diagnose each problem before suggesting solutions. The diagnosis is documented on Github by means of comments to the issue. Once an issue is closed, we edit the issue to minimize text and focus on the correct diagnosis.

  • Ampersand is under construction all the time. We accept the consequences and make them as bearable as we can.

  • We believe in a formal foundation of software engineering.

  • We seek to adopt sound software engineering practices that have demonstrated quality.

  • We want to reuse good software built by others, not only to save ourselves maintenance work, but also to benefit from things that others have done in a better way.

Contributions to the documentation

If you have anything to fix or details to add, just post a comment next to the paragraph. We really appreciate if you do so, because our readers know best what it is they are looking for in the docs.

You can do that by clicking the '+' icon that appears when you hover above the paragraph. Don't be shy! Try it out!

Licence

Unless otherwise specified, everything in this repository is covered by the following licence:

Creative Commons Attribution-ShareAlike 4.0 International

Ampersand Documentation by the the Ampersand team is licensed under a Creative Commons Attribution 4.0 International Licence.

Based on a work at https://github.com/AmpersandTarski/TheToolsWeUse