path: root/CONTRIBUTION.md

This file is meant to ease the onboarding of new contributors.

Introduction
============

TODO


Quick start for testers
=======================

```bash
$ git clone git://git.mageia.org/software/rpm/urpmi
$ cd urpmi
$ git checkout <branch_name>
    # Possible branches : 
    #    - topic/maat_color
$ dev/mogen
$ ./urpmi <options>
$ su -c "./urpmi --test <package_name>"
$ su -c "./urpmi <package_name>"
    # Warning this last command *really* installs the package
```

Quick start for coders
======================

```bash
$ git clone ssh://<username>@git.mageia.org/software/rpm/urpmi
$ cd urpmi
$ git branch topic/<new_branch_name>
    # This creates the new branch with current master as the starting point.
    # If you want to start from elswhere you need to master git branch command
$ git checkout topic/<new_branch_name>
    # This puts you on your new branch to start coding
$ dev/mogen
    # This generates the local translation .mo files for a translated display
    # If you work on translations you can use dev/mogen --watch in a dedicated term
    # and work in an other : translation will be updated in near realtime

    # While [ 1 ]
    # do
    # Coding & testing
git add <new_files>
git commit -m "Commit message" <new_files> <modified_files>
git push origin topic/<new_branch_name>
    # All these git commands allow you to publish your changes.
    # You'll need you have a dev account in Mageia system -> https://wiki.mageia.org
    # Make sure you master git enough and make sure to have a Mageia mentor to guide you
```


Good proctices & advices
========================

Coding standards & indentation
------------------------------

Coding standards are :
 * space indentation (no tabs)
 * 4 spaces for one indentation level
 * 4 spacesfor tabulations (and replace tabs by spaces)
 * Opening brackets on the same line
 * closing brackets on the line after

Commit messages
---------------

Commit standards are :
 * Language = english
 * One commit per change (do not mix multiple topics in a single commit)
 * Commit title should be short but allow to identify what's done
 * Commit message under the title can explain more 

Branches
--------

Unless you are working on an official branch your branch should be named topic/<username>_<yourkeyword>


Organization & architecture of the code
=======================================

Files and directories
---------------------

The thereafter tree is created with the command :
```bash
tree -I "locale|media|blib|t|pod|*.mo"
```

urpmi
├── ChangeLog
├── Changes
├── CONTRIBUTION.md
├── dev
│   └── mogen
├── gurpm
│   └── RPMProgressDialog.pm
├── gurpmi
├── gurpmi2
├── gurpmi.desktop.in
├── gurpmi.pm
├── inst.list
├── Makefile
├── Makefile.PL
├── MANIFEST
├── MANIFEST.SKIP
├── MYMETA.json
├── MYMETA.yml
├── pm_to_blib
├── po
│   ├── *.po
│   ├── Makefile
│   ├── POTFILES.in
│   ├── urpmi.pot
├── polkit
│   ├── Makefile
│   └── org.mageia.gurpmi2.policy.in
├── README.md
├── README.transifex
├── README.zeroconf
├── rpm-find-leaves
├── rurpme
├── rurpmi
├── skip.list
├── urpm
│   ├── args.pm
│   ├── bug_report.pm
│   ├── cdrom.pm
│   ├── cfg.pm
│   ├── download.pm
│   ├── get_pkgs.pm
│   ├── install.pm
│   ├── ldap.pm
│   ├── lock.pm
│   ├── main_loop.pm
│   ├── md5sum.pm
│   ├── media.pm
│   ├── mirrors.pm
│   ├── msg.pm
│   ├── orphans.pm
│   ├── parallel_ka_run.pm
│   ├── parallel.pm
│   ├── parallel_ssh.pm
│   ├── prompt.pm
│   ├── README.ka-run
│   ├── README.ssh
│   ├── removable.pm
│   ├── select.pm
│   ├── signature.pm
│   ├── sys.pm
│   ├── util.pm
│   ├── xml_info_pkg.pm
│   └── xml_info.pm
├── urpme
├── urpmf
├── urpmi
├── urpmi.addmedia
├── urpmi.bash-completion
├── urpmi.pm
├── urpmi.removemedia
├── urpmi-repository-http.service
├── urpmi.schema
├── urpmi.update
├── urpm.pm
└── urpmq

A few files are just information files :

├── ChangeLog
├── Changes
├── CONTRIBUTION.md <-- We are here
├── README.md
├── README.transifex
├── README.zeroconf
├── urpm
│   ├── README.ka-run
│   ├── README.ssh

Some files are generated by build or test process:

├── blib/*
├── locale/*
├── Makefile
├── MYMETA.json
├── MYMETA.yml
├── po
│   ├── *.mo
├── t
│   ├── media/*

Some files are used either to set up build or to test:
├── Makefile.PL
├── MANIFEST
├── MANIFEST.SKIP
├── po
│   ├── Makefile
│   ├── POTFILES.in
├── polkit
│   ├── Makefile
│   └── org.mageia.gurpmi2.policy.in

some are dev tools used to work on urpmii or buld/test:

├── dev
│   └── mogen
├── pm_to_blib


Some are the urpm* tools themselves:

├── gurpmi             <-- GUI for urpmi
├── gurpmi2            <-- GUI for urpmi too
├── rurpme             <-- r-urpm-i for retricted-mode urpmi
├── rurpmi             <-- r-urpm-e for retricted-mode urpme
├── urpme              <-- urpm-e for urpm "erase" : uninstalls software
├── urpmf              <-- urpm-f for urpm "find file" : searches for a file in software
├── urpmi              <-- urpm-i for urpm "install" : installs softvare
├── urpmi.addmedia     <-- adds a new medium (source of software)
├── urpmi.removemedia  <-- removes a medium
├── urpmi.update       <-- updates a medium
└── urpmq              <-- urpm-q for urpm "query" : search for softvare (by name...)

Some are config files that will be put in the system during install and used by urpmi:

├── gurpmi.desktop.in
├── inst.list
├── skip.list
├── urpmi.bash-completion
├── urpmi-repository-http.service

Some are translation files:

├── po
│   ├── *.po
│   ├── *.pot

And the rest are .pm files = librairies called by the "main" programs urpm*

├── gurpm
│   └── RPMProgressDialog.pm
├── gurpmi.pm
├── urpm
│   ├── args.pm
│   ├── bug_report.pm
│   ├── cdrom.pm
│   ├── cfg.pm
│   ├── download.pm
│   ├── get_pkgs.pm
│   ├── install.pm
│   ├── ldap.pm
│   ├── lock.pm
│   ├── main_loop.pm
│   ├── md5sum.pm
│   ├── media.pm
│   ├── mirrors.pm
│   ├── msg.pm
│   ├── orphans.pm
│   ├── parallel_ka_run.pm
│   ├── parallel.pm
│   ├── parallel_ssh.pm
│   ├── prompt.pm
│   ├── removable.pm
│   ├── select.pm
│   ├── signature.pm
│   ├── sys.pm
│   ├── util.pm
│   ├── xml_info_pkg.pm
│   └── xml_info.pm
├── urpm.pm


Architecture and libraries organization
---------------------------------------

TODO



Urpmi internals
===============

TODO




Roadmap
=======

TODO




Contributors
============

Lets pay here our tribute to the heroeswho created andcontributed to urpmi...

TODO