Code Contributions

We would like to thank you for your interest in contributing. You can find below how you can get started with knowing and contributing to moja global. The first few steps are always crucial but signify how you wish to involve with the community.

1. Get to know moja global:

   • Read the Contributing guidelines
   • Read the Code of Conduct.
   • Review the Coding guidelines and Contribution criteria.
   • Review the bug-list, open issues, Project Board (if you want to code a new feature) or the Strategic Plan. To start a new Project follow these guidelines.
   • Contact the Coach, if available in the README document, or the Repository Maintainer by submitting an Issue with an @mention.

2. Join the moja global organisation

3. Fork the repository if you do not want to join moja global or want to start working before your request to join has been approved.

4. Follow Vincent Driessen's Git Branching System:

   • Name your Branch with the same name using the Feature or Branch name with a version number.

5. Make your contribution

   • Make changes or additions to the code.
   • Ensure that your code meets the coding style guidelines.
   • Perform relevant tests, which includes unit-testing or end-to-end testing as found fit for the repository that you will be submitting the pull-request for.
   • Follow the documentation guidelines.

6. Submit your contribution

   • Submit a Pull-Request to the Branch you want to contribute.
   • Use a clear and descriptive title.
   • Ensure maintainers can understand your proposed changes from the description.
   • Sign your message with Signed-off-by: Random J Developer to agree to Developer Certificate of Origin (DCO) to certify that you wrote or otherwise have the right to submit your contribution to the project.
   • Ensure your Pull-Request passes all checks and has no conflicts.
   • Click Create Pull Request.
   • Include in the comments section the tests that you have completed and if they were a pass or fail.

7. Get credit for your work

   • Claim credit if you are not listed yet.

If you have experience and want to help, please send an email to mentorship@moja.global. We are open to mentoring new developers and contributors through various mentorship program and initiatives.

Starting a new project

moja global is increasingly looking for new scientists, developers and researchers to join us and help improve our processes. We are also looking to collaborate on the development of new projects that serve our strategic plan and mission. Please have a look at the following steps to start a new project:

1. Avoid Duplication:

   • Before starting a new project, review whether a project based on your idea already exists:
     • All projects are listed in the Project tab of the moja global root directory.
     • Please also review the existing repositories, as not all may be listed under the "Project" tab.
     • Finally, have a look at the Strategic Plan for this year, if your idea might be worked upon.
   • If your project idea already exists, please join forces with those already active. Else (if your project does not exist) proceed with the next step.

2. Build on what already exists:

   • If you can build on code that is already available, coordinate your project with the maintainers of the relevant repository by requesting a new feature.
   • If there is no existing code base to start from, create a repository even if you are not part of the moja global organisation (yet).

3. Create a project board to track and update your work:

   • If you are a part of the moja organisation use the project list under About_moja_global.
   • If you are not (yet) part of the moja global organisation, use the projects list in your repository. You can notify the wider moja global community by opening an issue under About_moja_global informing that you have started a new project.

4. Invite your team:

   • Invite your team to join the project even if they are not part of the moja global organisation
   • Nest your team into the right parent team, which means the repository team for new projects or the moja-global team for new repositories
   • Assign roles for Scientists, Engineers, Editors, Maintainers (for code and science). Try to have at least 2 persons for each role to avoid overloading your team.

5. Build a Science Design:

   • If your project has any scientific component, you will need to have a Science Design for your project.
   • If your project is revising or adding to an existing module, the original Science Design can be revised.
   • Follow these steps: The processes for both developing new or revising existing Science Designs are the same.

6. Follow the regular project implementation cycle

Creating a new repository

A repository contains all the files and the revision history associated with a project under development. moja global uses repositories to store files, revision history, carry out discussions, manage the project work and accept contributions from our diverse contributors. To get started with creating a repository, please follow these steps:

1. If you are a member of the moja global organization, define a new repository:

   • Use a short version of your title as the repository name: moja-global/repository-name.
   • Use the full title as the description of the repository.
   • Make the repository public.
   • Initialize it with a README file which includes the abstract of the project.
   • Create your repository.

2. If you are not a member of the moja global organization, the moja global team will create the repository for you and invite you as an external member to take charge of the project. Follow these steps:

   • Navigate to the About_moja_global repository.
   • Click Issues.
   • Click the green button Get Started in the Feature Request box.
   • Use the title of your project as the title of the requested features.
   • In the body of the Issue, provide the abstract of your project first. Then follow the template to the extent it is useful and provide as much information as possible.
   • Attach files, screenshots and/or animated GIFs
   • Click the green button "Submit New Issue" at the bottom right corner.
   • If you have not received a reply within 2 days, please write us at tsc@moja.global.

Develop a Test

Tests are an important component of the pull-request/merge process. If you are developing a new module or project, it is likely that standardised tests will not already be available. In this respect it is good practice to develop standard tests for your new code that can be applied to ensure the code is performing as expected.

Project implementation

This process assumes that you already have started a new project and have an approved Science Design

1. Confirm Your Team:

   • Contact the maintainers and documentation writers of the repository you want to code for and discuss your project. Agree upon the write and maybe the admin permissions. Assign additional maintainers and documentation writers as needed.
   • Assign a Coach who is willing to introduce new developers to the project.
   • Publicise widely that the project is ready to be developed and is looking for engineers, documentation writers, testers and more. When moja global users collaborate everybody wins. Contact tsc@moja.global to get support with reaching out to the community of users.
   • Emphasize to all new contributors to review the Coding Guidelines and the Contribution Criteria.

2. User Stories and Minimum Viable Product:

   • Use User stories to translate a Science Design into a task list that can be engineered and developed.
   • When the scientific design is approved, organise a conference call with all the science contributors (at a minimum the maintainers of the Science Design have to be present) and the interested developers (at a minimum the maintainers of the future code should be present) to contribute to the project. Real-time interaction is important so it would be better to have fewer participants on a call rather than more participants through a written document.
   • The developers can ask for clarifications from the scientists to ensure that every aspect of the Science Design is clear.
   • Next developers and scientists individually draft all the user stories they can think of, into the GitHub Project Board. All user stories will have the following syntax: As a [User, Admin, …], I can [action: click, scroll, …] to [result: calculate, open, load, erase, …].
   • After a first drafting session, the User Stories are classified as essential or later. All the User Stories classified as essential must be part of the Minimum Viable Product (MVP) which means that none of them can be dropped without breaking the why of the project. Check every user story several times to check whether it can be dropped from the MVP.
   • All the User Stories are moved to the To do column of the GitHub Project Board. The MVP stories are moved to In progress.

3. Agile Architecture:

   • Agree on an initial project architecture with the software development team. This improves communication, increases the speed and quality of the coding while reducing risks.
   • There are no fixed rules about what you should define up front. Your minimum outcome is that everybody agrees on how the project should be built and how it should fit into the wider software components.
   • It is logical to define the interactions with the existing system and sketch a technology diagram linking the user interface with the business process and with the data.
   • Use branding and User Interface Style of the wider software components.

4. Iterative Build:

   • Build the MVP in the initial sprint.
   • Document the code in the code base and in the Wiki. Everybody can edit the Wiki. If you wish to create documentation that needs a maintainer approval, use regular Markdown files.
   • Develop tests, in collaboration with Scientists, to check whether the software is working accurately. The code is tested continuously based on these tests. The tests are upgraded continuously with the code.
   • Invite feedback from users after every sprint. The feedback is used to improve documentation in the Wiki and to update the backlog.
   • Take the feedback into account when you prioritize the backlog and start a new sprint.
   • Continue this cycle until the project is ready for a first release.

5. Approve Release:

   • Once the code is ready for release, document the tests that have been performed, copy the Wiki to the repository and create a release-candidate version that includes the Wiki and all other documentation.
   • Submit the pre-release to the scientists and code maintainers for a final review.
   • Invite the independent scientists to participate in the review if a science review panel was used. Document test results and feedback from the reviewers and maintainers.
   • Complete all the tests and bug-fixes.
   • Submit the pre-release with a pull-request, and indicate that you want @TSC to review your pull-request.
   • The project will be released with the agreed version number.

Report a bug

moja global is increasingly looking for new scientists, developers and researchers to join us and help improve our processes. We are also looking for constructive bug triage process is carried out to help us improve our software, workflows and processes. Please have a look at the below steps to get started with reporting a new bug as a user:

1. Navigate to the main page of the repository where you found the bug.
2. Under the repository name, click Issues.
3. Click the green New Issue button
4. Click the green button Get Started in the Bug Report box.
5. Use a clear and descriptive title.
6. Follow the template and provide as much information as possible
7. Attach files, screenshots and/or animated GIFs
8. Click the green button Submit New Issue at the bottom right corner

We would also like the users to review the following if they are not familiar with GitHub and standard bug-reporting processes:

• Opening an issue from code
• Creating a permanent link to a code snippet

Feature Request

moja global is increasingly looking for new scientists, developers and researchers to join us and help improve our processes. We are also looking for constructive feature development via feature requests to help us improve our software, workflows and processes. Please have a look at the below steps to get started with requesting a new feature as a user:

1. Navigate to the main page of the repository for which you want to propose a new feature or functionality. If you want to propose a new tool or module, please navigate to the About_moja_global repository.
2. Under the repository name, click Issues.
3. Click the green New Issue button
4. Click the green button Get Started in the Feature Request box.
5. Use a clear and descriptive title.
6. Follow the template and provide as much information as possible.
7. Attach files, screenshots and/or animated GIFs.
8. Click the green button "Submit New Issue" at the bottom right corner.

If you would also like to build the proposed feature, please also review how to start a new project.

Standard tests

Testing needs to be performed by both developers and maintainers for new or modified code. Developers are expected to perform standard tests before submitting the pull-request, and maintainers also conduct testing when going through the process of assessing a pull-request.

Tests suites should be included in the repositories of existing code, and test suites should be developed for new repositories where tests do not already exist. The standardised test suites are expected to be completed for all pull-requests. A standardised test suite should include:

1. Unit tests
2. Integration tests
3. System tests

Unit tests are used to test individual components of the code for example a function or procedure. These should be performed by both contributors and maintainers.

Integration tests are used to test the integration of the different units to ensure that the different functions/procedures and modules are interacting correctly. These should also be performed by both contributors and maintainers.

System tests involve testing the complete integrated system, this includes performance tests and guidelines on speed performance to ensure that any new features or bug fixes do not compromise system performance.

These tests need to be performed by the maintainer, and the maintainer may also use independent testers if possible. Failure of a system test, or poor performance and may result in non-acceptance, or a request to improve performance before the pull-request if performance is accepted.

If you have experience and want to help, please send an email to tsc@moja.global. We are looking for test engineers with experience testing C++ code bases or auditing greenhouse gas inventories.

Continuous Integration Tools

While not yet implemented, moja global intends to utilise Continuous Integration Tools. Continuous Integration allows multiple developers to work on a software project while integrating their changes and maintaining the stability and quality of the software.

Continuous Integration fosters innovation by ensuring that ongoing improvements are always available and compatible to a set of users. This would allow a user developing their own countries implementation could progressively add new data and features while maintaining a functioning, reproducible system

It is not yet known the level of activity and rate of development that is likely to occur within moja global repositories to bring Continuous Integration tools within the folds. Therefore it is difficult to specify how often integration should occur, and this would need to be assessed on a case-by-case basis for each repository.

Two Integration Tools have been identified for Continuous Integration with moja global:

• Travis CI supports Continuous Integration and testing for Linux.
• AppVeyor supports Continous Integration and testing for Windows.

Both services offer free packages for open-source projects. Please send us an email at tsc@moja.global if you would like to contribute towards the same.

moja global Versioning

Most moja global tools are platforms combined with modules. This results in many dependencies which requires tight version control without losing any flexibility.

moja global projects use Vincent Driessen's GitFlow and therefore moja global uses the related versioning system. You can find a more elaborate discussion on the following discussion of SemVer.

The Standard Format for the version number consists of 3 indicators: MAJOR.MINOR.PATCH. It is only assigned at the moment the version is released. For a work in progress, a label is used as a placeholder.

Standard Format

The indicators in the version number will be changed as follows:

1. MAJOR is increased when you:

   • Make backwards-incompatible changes.
   • Change the Science Design so a restructuring of the code or re-development of the whole module is required.

2. MINOR is increased when you:

   • Make backwards-compatible changes.
   • Change the Science Design so the code changes within the existing framework are required.

3. PATCH is increased when you:

   • You make backwards-compatible bug fixes.
   • Change the Science Design so no code changes are necessary.

Build Versioning

• Feature branches and the develop branch should always build snapshot versions including the date. Example: 2.6.0-SNAPSHOT201205012.
• Release branches and hotfix branches should always build release candidate versions. Example: 2.6.0-0.rc1.
• The master branch should always build unqualified versions - versions without build numbers. Example: 2.6.0.

The developer or scientist needs to judge whether to increase the MAJOR, MINOR, or PATCH for the SNAPSHOT version. The maintainers will revise this number when the proposed changes are submitted as a pull-request.

Contribution Credits

GitHub automatically records all contributions to code and documentation under the Insights/Contributors tab.

In addition, moja global is using the All Contributors Bot to recognize all contributors for a wide range of possible contributions.

But if you would like to be recognized, please blow your own trumpet by following the steps below:

1. After making your contribution (submitting your pull-request, replying to a question, resolving issues and more) add the following sentence in a comment to an existing issue:\ @all-contributors please add <@username> for <contributions>
2. <@username> can be any person or organisation with a GitHub account.
3. <contributions> can be any word from this list but the bot will also use basic Natural Language Parsing to determine your contribution intent.
4. Submit your comment.
5. The Allcontributors Bot will submit a pull-request to include <@username> among the list of contributors
6. Once the pull-request is accepted by the maintainer of the repository, <@username> will be added to the list of contributors for the suggested <contributions>.