Commit 8bfa79af authored by Millian Poquet's avatar Millian Poquet
Browse files

[doc] deprecate markdown CONTRIBUTING

parent b2c51925
# Table of contents
- [Overview](#overview)
- [How to contribute?](#how-to-contribute)
- [Hacking Batsim](#hacking-batsim)
- [How to release a new version?](#how-to-release-a-new-version)
# Deprecated
Batsim contributing guidelines have moved.
# Overview
Batsim uses different git repositories.
The main repositories and their role are listed below:
- [github](
- used as a **public gateway** for **external** contributors:
- external [issues](
and enhancement proposals
- external [pull requests](
can be done to share your modification with us
- [inria's gitlab](
- used as a perennial public gateway (Github may disappear randomly)
- main entry point for **internal contributors** (*not* for main developers):
- internal [issues](
(some of them may be confidential and require login)
- internal [merge requests](
can be done to share your modifications
- [GRICAD's gitlab](
- entry point for **main developers**:
- [continuous integration](
is there.
This CI setup is built on top of Gitlab CI.
There are existing runners on GRICAD's infrastructure.
More information on our CI setup can be found
Furthermore, these repositories are in the Batsim ecosystem:
- [evalys]( includes visualisation tools of
most Batsim outputs
- [batexpe]( contains scripts to ease
the management of experiments with Batsim.
Such scripts are expected to deprecate ``tools/experiments`` scripts located
in Batsim's repository.
- Different schedulers can be plugged to Batsim:
- the schedulers from [OAR 3](, thanks to
the [bataar](
- [pybatsim]( contains resource
management algorithms in Python 3.
- [batsched]( contains general purpose
and energy oriented resource management algorithms. It is implemented in C++.
- [datsched]( contains some algorithms
implemented in D.
- Resource management algorithms in Rust can be found
# How to contribute?
If you encounter any bug in Batsim, please open an issue:
- external user: use [github](
- internal user: use [inria's gitlab](
It will allow us to know that the bug exists, and will help a lot resolving the
problem ;).
If you want to request a new feature, you may also write an issue or
contact us by email.
If you want to share any improvement on the Batsim code,
please make sure you follow [coding conventions](#coding-conventions)
then you can use the following mechanisms so we can include your modifications:
- external user: [github pull request](
- internal user: [inria's gitlab merge request](
# Hacking Batsim
This little section explains a few choices that have been made when implementing
Batsim. Coding conventions are first given to maximize the project code
homogeneity. The different subsections then explain some code aspects.
## Coding conventions
The existing code base tries to follow the following conventions.
- Header files should have the ``.hpp`` extension.
Source files should have the ``.cpp`` extension.
- Variables, functions and methods should be lowercase,
and underscore ``_`` should be used as the word separator.
Example: ``int my_fancy_integer = my_wonderful_function(42);``
- ``using`` should NOT be present in header files.
- Classes should be in UpperCamelCase. Example: ``MyBeautifulClass instance;``
- The code should be indented respecting the
[Allman style](
- Curly brackets ``{}`` should be present even for one-statement blocks.
## SimGrid process spawning management
Batsim is composed of multiple SimGrid processes. Most spawned processes have
parameters. A ``struct`` should be used to store the process arguments (even
for simple parameters, as more arguments may arise in the long run).
An instance of this parameters ``struct`` should be allocated dynamically
before spawning the process, and the process should deallocate the memory of
this instance.
The following example shows the code implied in spawning the ``execute_job`` process.
``` C++
// Arguments of the execute_job process
struct ExecuteJobProcessArguments
BatsimContext * context;
SchedulingAllocation * allocation;
// Calling function
int server_process(int argc, char *argv[])
// ...
// Allocates memory for the execute_job process parameters
ExecuteJobProcessArguments * exec_args = new ExecuteJobProcessArguments;
exec_args->context = data->context;
exec_args->allocation = allocation;
// Spawns the execute_job process
MSG_process_create("job_executor", execute_job_process, (void*) exec_args, host);
// ...
// Process function
int execute_job_process(int argc, char *argv[])
// Get input parameters
ExecuteJobProcessArguments * args = (ExecuteJobProcessArguments *) MSG_process_get_data(MSG_process_self());
// ...
// Cleans memory
delete args;
return 0;
In brief, if one wants to add a new process in Batsim, it should be done as follows
- create a new function named ``int something_process(int argc, char *argv[])``
where ``something`` should be replaced by the process name. This function
should return 0 and deallocate the memory of its arguments.
- create a ``struct SomethingProcessArguments`` to store the arguments of
the process
## Communication between SimGrid processes
Processes may communicate with other processes via messages. The messaging
system uses SimGrid mailboxes, but the ``send_message`` function should be
used for the sake of code homogeneity.
Files ``ipp.hpp`` and ``ipp.cpp`` define functions and structures related to
inter process communications. All messages must be typed. The IPMessageType
enumeration stores the possible values:
``` C++
enum class IPMessageType
JOB_SUBMITTED //!< Submitter -> Server. The submitter tells the server that a new job has been submitted.
,KILLING_DONE //!< Killer -> Server. The killer tells the server that all the jobs have been killed.
// ...
If a message has associated data, a specific ``struct`` should be defined for it
(even for simple parameters, as more parameters may arise in the long run).
In the following example, a job executor tells the server that the job has
``` C++
int execute_job_process(int argc, char *argv[])
// ...
// Allocate memory for the message
JobCompletedMessage * message = new JobCompletedMessage;
message->job_id = args->allocation->job_id;
// Send the message to the server
send_message("server", IPMessageType::JOB_COMPLETED, (void*)message);
// ...
int server_process(int argc, char *argv[])
// The server waits and receives the message
msg_task_t task_received = NULL;
IPMessage * task_data;
MSG_task_receive(&(task_received), "server");
// Data associated with the SimGrid message
task_data = (IPMessage *) MSG_task_get_data(task_received);
if (task_data->type == IPMessageType::JOB_COMPLETED)
// Gets the message content
JobCompletedMessage * message = (JobCompletedMessage*) task_data->data;
// ...
// ...
// Cleans the task_data AND the underlying task_data->data
delete task_data;
In brief, if one wants to add an inter process message type in Batsim,
it should be done as follows:
- add a new ``SOMETHING`` enumerated value in the ``IPMessageType`` enumeration
- if needed, create a new ``struct SomethingMessage`` if data is associated with
the message.
- make sure the new ``SOMETHING`` enumerated value is handled correctly in the
``std::string ip_message_type_to_string(IPMessageType type);`` function.
- make sure the new message type is destroyed correctly in the ``IPMessage``
# How to release a new version?
1. Determine what version should be released,
following [semantic versioning]( rules.
Major version should be changed whenever an incompatible change occurs on the CLI or the protocol.
2. Update the [changelog](docs/changelog.rst).
Try to mention all modifications since last release: ``git diff``
3. Bump version in [VERSION](./VERSION)
4. Tag new version (with annotations): ``git tag -a vX.Y.Z``
Put the changelog of the new release in the long description.
They can now be found [there](
as part of the [batsim readthedocs](
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment