Clone

HTTPS: git clone https://vervis.peers.community/repos/yEzqv

SSH: git clone USERNAME@vervis.peers.community:yEzqv

Branches

master

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.

[See repo JSON]