The documentation repository of the MOOSE framework. Note that the contents of this repo get generated from the MOOSE lua code, which is contained within the MOOSE main repository.
** UNDER CONSTRUCTION **
So, you are already familiarized with Lua and you think the best way to get the new feature you want fast is to program it yourself ? Or you feel like reporting bugs isn’t enough, you want to fix them yourself ? Either way, you need some more information to contribute to Moose.
This guide assumes that you are already familiar with Moose and that you already set up your development environment. If it is not the case, please go through the Tester Guide before proceeding.
In this document, we will review
You are assumed to be familar with at least the basics of GitHub (branches, commits, pull requests…). If it is not the case, please at least read this tutorial. If something isn’t clear still, ask us, we’ll be glad to explain!
Moose is in fact located on three repositories :
On the MOOSE repository, three branches are protected, which means that you cannot merge or commit directly to them, you need to create a pull request;
You are encourgaed to create your own branch, named after you pseudonyme, to test stuff and do some small-scale bugfixes. When you want to work on bigger features, you should create a new branch named after the feature you are working on. Don’t forget to delete it when the feature is merged with master!
The usual Git commit guidelines apply. Don’t overthink it though, time is better spent coding or managing the Issue Tracker than writing long-form commit descriptions.
When the code you are working on is finished, you will want to resolve the merge conflicts between your branch and master, and then create a pull request. Explain clearly what your code does (with a link to the relevant issue). If it meets the requirements below, it will be approved ASAP by FlightControl.
We try to follow a contribution process, to make sure we work efficiently together. It isn’t set in stone, but it gives an idea of what should be done. We wouldn’t want two contributors both working on the same issue at the same time, would we ? This process is more geared towards the implementation of new features, the process for bug fixes is more flexible and several steps can be overlooked.
To ensure a good degree of consistency in Moose’s code, we follow the following standards :
SPAWN
)Core.Base#BASE
GetName()
)_GetLastIndex()
)IndexString
)BASE
:
F()
, F2()
and F3()
for function calls,T()
, T2()
and T3()
for function logic,E()
for errors.The Luadoc system is not only useful for the contributor to understand the code, but also the mission designer, as it used to automatically generate the HTML documentation. It thus needs to follow some strict standards. Keep in mind the following informations :
---
).@{Module#CLASS.Method}
for a method@{Module#CLASS}
for a classModule
can be ommited if the hyperlink points to the same module (e.g. @{#CLASS
} is valid if CLASS is in the Module the link is in)Folder.Module#CLASS
(a Moose class)Dcs.DCSTypes#Class
(a DCS class)#string
#number
(integer or floating point)#boolean
#nil
Every new file should contain at least one module, which is documented by a comment block. You can copy paste the following model and fill in the blanks :
--- **Name of the Module** - Short Description
--
-- ===
--
-- Long description. Explain the use cases.
-- Remember that this section will be red by non programmers !
--
-- ===
--
-- ### Authors : Your name/pseudnyme
--
-- @module Module
Every class should be documented by a comment block. You can copy paste the following model and fill in the blanks :
--- **Name of the CLASS** class, extends @{Module#CLASS}
--
-- Long description. Explain the use cases.
-- Remember that this section will be red by non programmers !
--
-- @type CLASSNAME
-- @field #type AttributeName (add a @field for each attribute)
-- @extends Folder.Module#CLASS
Every method should be documented by a comment block. You can copy paste the following model and fill in the blanks :
--- Description of the method
-- @param #type (add a @param for each parameters, self included, even if it's implied)
-- @return #type (add other @return fields if the method can return different variables)
-- @usage (can be omitted if the usage is obvious)
-- -- Explain how to use this method
-- -- on multiple lines if you need it !
To ensure that the next Release of Moose is as bug-free and feature rich as possible, every Moose contributor respects a release cycle.
The key takeways are:
You can see Milestone as the GitHub way to say Release. Moose repository has three active Milestone at any time :
Every bug is assigned to the next milestone, and should be fixed before the release. Features are assigned to any milestone depending on the importance of it and how hard it is to implement. Typically, a feature that is currently worked on is assigned to the next milestone, an very long-term feature is assigned to Moose-Future, and any other feature is assigned to the milestone after the next one, the goal being to have a nice todo list for the contributor to pick and choose from at the end of feature freeze. If you come accross a issue that isn’t assigned to a milestone, feel free to add it to the correct one !
We heavily use GitHub’s label system on the Issue Tracker to categorize each issue. Each issue is assigned the relevant label(s) at birth by a contributor, and they are then updated to reflect the current state of the issue. If you come accross an untagged issue, feel free label it ! You can consult the full list of labels available, but please asks the community before adding or removing a label to the list.