M.O.O.S.E.

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.

View the Project on GitHub FlightControl-Master/MOOSE_DOCS

** 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

  1. GitHub/Git organisation
  2. Contribution guidelines
  3. Coding standards
  4. The Luadoc
  5. Moose release cycle
  6. The Issue Tracker : labels and milestones

1) GitHub/Git organisation

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!

1.1) The Repositories

Moose is in fact located on three repositories :

1.2) Branches

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!

1.3) Commits

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.

1.4) Merge/Pull Requests

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.

2) Contribution guidelines

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.

  1. Think about what you are trying to achieve. Writing some pseudocode is a great way to undersatnd the challenges you are going to face.
  2. Discuss your idea with the community on Slack. Maybe there is a way to do it you didn’t even think about, or maybe you could team up with someone who is already working on it!
  3. Create a high level design document. It doesn’t need to be thorough, but you need to have an idea of which class do you want to write, which class they should inherit from, which methods are needed in each class…
  4. Write an issue on GitHub with your high level design document, apply the label “enhancement” to it, and assign it to yourself.
  5. Create a new branch named after the feature on MOOSE’s repository to work on (you will be given contributor access).
  6. Write your code in this branch, following the Coding Standards. Sync fairly regularly this branch with master, so that you don’t have tons of merge conflicts at the end.
  7. When done, write a/some test mission(s) to showcase how to use your feature to the community.
  8. Generate the Luadoc.
  9. Relsove merge conflicts with master and create a new pull request.
  10. Delete your branch if you are not going to use it again.

3) Coding Standards

To ensure a good degree of consistency in Moose’s code, we follow the following standards :

4) The Luadoc

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 :

4.1) Modules

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

4.2) Classes

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

4.3) Methods

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 !

5) Moose release cycle

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:

6) The Issue Tracker : labels and milestones

6.1) Milestones

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 !

6.2) Labels

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.