Contributing to Massively Modified Projects is not difficult, but it does require adhering to some guidelines. Our projects are mostly all node projects and are built with similar structure. This means that our process for development is mostly seamless between all of our projects.
If you like our software, please consider making a donation. Donations help greatly to maintain the Massively Modified network and continued support of our open source offerings:
Table of Contents
- Our Projects
- Install & Build
- The Workflow
- Issues First
- Fork Next
- Branch Beyond
- Submit Often
- Things to Review
- What to Do
- Become a Member (coming soon!)
- Contribute Code
- Test Code
- Adhere to Our Coding Standards
- Adhere to Our CSS Naming Conventions
- Make a Donation
Other Project Types
The guidelines for contributing to other project types can be found at the following pages:
- C/C++ (coming soon!)
- Npm (Usually included with Node.js)
Install & Build
The remaining dependencies are installed via npm:
git clone https://gitlab.com/mmod/<project-name-here> cd <project-name-here> npm install
At this point several dependencies will have installed. Once your terminal/command prompt stops spewing information, you may proceed with building the project for the first time:
That's it! You can open the
index.js file located in the root directory to direct attention to module specifics, or of the
src directory to work on major/minor and/or other functionality.
You can browse the
gulpfile.babel.js file for the tasks that are used in building the application, and make use of them individually as you require in order to accomplish your goals.
There is also a
watch task available which will run the builds automatically as changes are detected in TS and SCSS files.
Before submitting a pull request, we require that all test pipelines pass. You can ensure that you have not broken anything by running the included test(s):
However, you should be able to add to the test.ts file depending on what you are adding, to ensure that your new bug-fix/enhancement/feature is covered in the test. If you are working on code-coverage:
npm run coverage
will test just that, and provide you with the feedback you need to increase code coverage.
Creating and submitting a Merge Request is one of the later bits of contributing code. Up until now we've covered how to get started with working in a project, more specifically how to get your environment set up - but we have yet to cover just how the process to working with our projects works.
Our workflow looks like this:
- And cloning
- Submitting often!
- For Assignment
- For Review
- By Assignment
- And inclusion
Now let's go over the work flow more in-depth:
There should be an issue created for the bug, enhancement, and/or feature that you are working on. If there isn't already one, then please create one.
When you create an issue (and often times, most bugs, enhancements, and/or feature requests will be submitted by end-users not following these guidelines), there is a format that you should adhere to:
The issue should be named as one would name a product backlog item. This means that instead of naming an issue, for instance, "Fix output of text to the console", the issue should be named:
As an end-user, I would like there to be a neatly presented and properly formatted output to the console.
The issue should be labelled appropriately. If you are creating the issue, please label it properly: Bug for Bug, Feature for Feature Request, Enhancement for Feature Enhancement, etc. If it's a security issue, you can additionally add the Security tag.
If you did not create the issue, and do not have privilege to label it properly, please communicate with the team to do so for you.
The issue should be assigned to you if you intend to work on it. If you are unable to assign yourself to the issue, then you will need to submit a merge request of the branch you create to work on the issue on your fork ahead of time. This will signify to those involved that you intend to work on the issue.
There is a proper way to name your branch, please continue reading to learn how to do so before you submit a merge request as an intent to work on an issue.
Create a fork of the project to manage your contributions with. This is self explanatory, so we won't cover it any further.
Clone your fork of the project to your local development machine and create a branch to work on your new feature, feature enhancement, or issue resolution. Name it by following these guidelines, separating each part by an underscore:
1 Specify the issue id. 2 Specify the type, such as: Feature, Enhancement, Fix. 3 Specify the name or description of the feature, enhancement, or bug. 3 Specify your name. 4 Specify your email.
If you are looking to submit a new feature that allows for providing custom regex, and the issue id is 183, the branch should be named as follows:
If you are looking to submit a bug fix that resolves an issue with the plug-in crashing when it parses a version string with a prerelease component, and the issue id is 183:
On your new branch, proceed to implement your feature, enhancement, or issue resolution. At any point you may submit a merge request.
You might think that submitting a merge request should be the last thing you do. When you're considering having your code merged then you are correct. However, merge requests (the pull requests of Gitlab) are one of the best ways to ask for code review - a practice that everyone should implement.
Submit for Assignment & Review
Sometimes you wont be able to assign yourself to an issue and will need a way to signify to others (especially the team) that you are working on an issue.
Yet at he same time, even if you're assigned, its recommended that you open your code for peer review - which could significantly reduce the time-to-inclusion.
In either case, you simply create a merge request and leave the assign to empty. This indicates to the team that you are still working on the issue, but are open for review. If you're not assigned, at this point we'd typically go ahead and assign the issue to you.
Even after you submit a merge request, you can continue to push to your development branch. In doing so, the merge request will automatically update; Any pipelines will run on your updated merge request again, and a new set of peer comments can be applied, searchable over the new state of your merge request (Isn't Gitlab great?)
While you'd obviously need an account to submit a merge request, the point of the name and email is so that we can add your name and email to the authors list with out specific correspondence dedicated to asking how you'd like to be added. Please be sure to specify the name and email as you'd like to be added.
Regardless, we may very well cherry-pick and making edits as necessary to merge requests prior to merging. To avoid this, please be sure to follow all the the aforementioned guidelines, submit a merge request with nobody assigned early and keep up on conversation, and follow the coding standards and naming conventions.
As already discussed in the previous section(s), merge requests may remain open for the duration of your development, and you may continue pushing new commits to your development branch - which will automatically update the merge request, clearing the slate for a new set of searchable conversation, and run any pipelines on the updated code-state.
The procedure for indicating that you are asking for the final review which would result in your code being merged, is to assign the merge request to a team member with privileges to perform the actual merge.
Things to Review
- Please note that enhancements and new features should be sensible and adhere to the policy of 'minimal tools for rapid development' - or be some radical new feature that will change the world!
- The code should be well tested, should come with a unit test for each method introduced, and should not cause any existing tests to fail.
- When you make a merge request, our CI/CD will run the embedded pipelines/tests - of which yours should be included. We require that the CI/CD pipelines pass before we will review any assigned merge request and/or merge any new code.
What to Do
If you really, really want to contribute, but have no idea where to begin, here are some ideas:
- You can peruse the Issues list for Feature Requests, Enhancements or Bugs that are in need of attention,
- You can go through documentation and/or text and attack syntax/grammar issues.
- You could help out with support in the Issues section
- You could go through any
README.mdfile or even this Wiki and help make it better, i.e. by providing language translations.
Regardless of what you're approach is, feel free to clone a copy of the repository and contribute to the code base and/or documentation as you find yourself willing to do so.
To view the license for the documentation provided by this wiki, please visit the Wiki Homepage