Rel4tion-Wiki/projects/project-process.mdwn

Partager is a community project. Right now the size of this community is 1, but
when I say "community" in this context I mean that the project and its
components are created without central dictatorship. The only project-global
rules are the ethical basis and the spirit document ("statement of love") of the
project. Other things are technical decisions and conventions, and can be
changed according to needs and new ideas. Decisions should be made by consensus.

This lack of "managers" telling everyone what to do allows the project
development and management process to be flexible and open to improvements and
new ideas. Anyone can take any role, and even different roles in different
projects. There's no hierarchy, just hackers.

There are many different methodologies for software development and engineering,
and you can use whatever you like. But all the information, resources, tasks,
bugs etc. of the project still need to be managed responsibly to allow easy
cooperation and team work. The items below are some possible and suggested
components or pages you may want to have, just to give you ideas. __You don't
have to use them__, and you're welcome to suggest and try any new methods you
know. It depends on the type of the project - some projects have a lot of math,
models and research, while others are GUI applications relying on existing
backends.

Reference: [[!wikipedia Software_development_process]].

# Infrastructure

Create a page for the project under the appropriate project category. For
example, if it's a component of Razom, put the project page under Razom's page.
Add a link from the parent page to your new project page. Even if you decided to
not write much for now, at least include some contact info and a brief
explanation of the project's purpose. You can see all the standard structures
and subpages other projects have - but don't hurry, you can add them later.

Create a git repository on Partager's server. If for any reason you prefer to
use your own server or Savannah, it's fine but please explain why and discuss it
first. If you do use an external server, arrange a mirror on Partager's git
server.

# Requirements

Either on the project's page or on a "requirements" subpage, explain exactly
what the project is supposed to do. The problem, the idea of the solution,
features and scope. If it's complicated, you can do some research, write some
test program, experiment with existing software, upload relevant screenshots and
so on. If it needs to be thorough, make it thorough. At this early stage making
changes is easy, so take your time to think and add ideas and consider possible
problems which may appear.

This is also the time to make a list of existing similar and related software,
examine it, study its weaknesses and strengths, and make sure your new project
brings something new. By the way things like "joy of hacking" are justifications
too, but if that's the only rationale, you should probably try to join those
existing projects first and see if they can be used for Partager's purpose.

If after this proces you feel you do want to start a new project - go ahead. I'm
against the strict "never reinvent anything". Sometimes you just have a new
approach, or want to create software that is free, or want to work in a
community environment without a company intervening and without hierarchy. It's
okay, go ahead and start the project :-)

# Specification

Some Partager components, such as computer languages, need a specification.
However, I don't expect any Partager specification to look like something
written by robots. Make it exactly as format as needed - no more, no less.

If you feel the requirements are thorough and organized well enough, maybe you
don't need a specification at all. If you do need one, start by gathering the
requirements by category, organize them, explain in clear language. Create
diagrams (you can use Dia for that), sketch some APIs if you need.

If it's something which requires a very strict and stable specification, like
a protocol or a language, make sure it's as precise as needed. It's going to be
critical. But you can always insert jokes and puns, and use regular wiki pages
for it. No special page formats are needed - just make sure it's organized well,
there are sections and subsections, a table of contents, version control and so
on.

Actually, if you want to do serious full version control of a specification, you
can make it a new separate git repository. It's still possible to make it
visible as a compiled web page by running a markdown compiler (or ikiwiki) on
the source (or any tool matching the source format you use) and pushing the
result into the FTP-accessible underlay.

# Design

This is where you choose the software components, protocols, interfaces, and
tools your project will need. Plan the structure, the packages, the classes,
the entities and the relationships.

The way I see it, design is like art. If you do it like a robot, strictly
following design pattern books and copying all the ideas from existing projects,
you may be missing all the fun. It's especially true for large projects in which
there's significant innovation in the design. Make it flow like a river, like a
flying carpet. Make sure you have motivation and excitement! At least enough to
create an elegant reusable design with high cohesion and low coupling.

Since Partager is about community and free life, I imagine you won't have a
reason to create something if you don't enjoy the process. But if you just need
a tool for some other project, and this tool isn't that fun to make, consider
suggesting the project to other people! Ask in the community, maybe someone else
will find it interesting or exciting and help you.

Design with passion ;-)

# Implementation

Some guidelines for the code:

- Readable
- Hackable
- *Small* easy to understand files and modules
- Short functions with clear purpose
- Use common patters for common things, e.g. STL container iterators
- Don't optimize without need
- Coding conventions
- Make sure to put the license notice, add new sources to Makefile.am, etc.

Small is good. There's no pride in having tons of lines of code. Simple, short,
to-the-point. Put each advanced part in its own module/section with good
documentation. If stuck or confused, don't hesitate to go back to some design or
planning and then proceed with coding.

Document every non-trivial decision. You can keep a diary if you want, or write
about decisions and designs in a blog. Just make sure you don't end up
forgetting why you did things the way you did.

If there's a whole team of developers, use IRC and mailing lists to talk and
coordinate the work. Each developer should know her responsibility and current
task. If you plan to start some new task or feature, announce it. Let the other
developers know.

# Iterations

Sometimes, while writing the code you'll find new requirements or new design
goals or issues. It's probably a good idea to notify all the developers, since
they may be writing code based on the older design where the new issue is not
handled. So bring it to their attention.

You can then go to the design pages, make the necessary updates, decided what
needs to be changed in the code and the models, and make the change carefully
while fixing everything broken by the modifications.

Many of Partager's high priority features and ideas are not present in existing
desktop environments and user programs, which means there's little practical
experience to learn from. Some designs will naturally need many iterations. User
interfaces will need testing, refinement and research until polished and ready
for release. Building small units, one at a time, helps make these iterations
with minimal potential damage to other existing modules. Incremental may be your
friend here.

You can also make a plan for some expected iterations. Make a list of features,
and choose a group to implement in each iteration. It will allow testing and
feedback to start at an earlier stage. Of course it won't take into account the
unexpected problems and changed requirements/designs, but it will help handle
them when they come.