You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We welcome anyone who would be interested in contributing to `MLSysOps framework`.
11
-
As a first step, please take a look at the following document.
12
-
The current document provides a high level overview of `MLSysOps framework`'s code structure, along with a few guidelines regarding contributions to the project.
7
+
# 🛠️ How to Contribute
13
8
14
-
## Table of contents:
9
+
Welcome! 👋 We're thrilled you're considering contributing to the **MLSysOps Framework**. This guide will help you get started.
15
10
16
-
1.[Code organization](#code-organization)
17
-
2.[How to contribute](#how-to-contribute)
18
-
3.[Opening an issue](#opening-an-issue)
19
-
4.[Requesting new features](#requesting-new-features)
20
-
5.[Submitting a PR](#submitting-a-pr)
21
-
6.[Style guide](#style-guide)
22
-
7.[Contact](#contact)
11
+
---
12
+
13
+
## 📌 Table of Contents
14
+
15
+
-[Ground Rules](#-ground-rules)
16
+
-[Code of Conduct](#-code-of-conduct)
17
+
-[Ways to Contribute](#-ways-to-contribute)
18
+
-[How to Submit a PR](#-how-to-submit-a-pr)
19
+
-[Writing Good Commit Messages](#-writing-good-commit-messages)
20
+
-[Issue Labels](#-issue-labels)
21
+
-[Branching Strategy](#-branching-strategy)
22
+
-[Contact](#-contact)
23
23
24
-
## Code organization
24
+
---
25
25
26
-
The MLSysOps framework is structured as follows:
26
+
## 📋 Ground Rules
27
27
28
-
TBC
28
+
- Be respectful and considerate to others.
29
+
- Make sure your contributions align with the project's goals.
30
+
- Write clear, concise, and grammatically correct Markdown.
31
+
- Ensure documentation and code are easy to read and understand.
32
+
- When in doubt, open an issue and ask for guidance.
29
33
30
-
## How to contribute
34
+
---
31
35
32
-
There are plenty of ways to contribute to an open source project, even without changing or touching the code.
33
-
Therefore, anyone who is interested in this project is very welcome to contribute in one of the following ways:
36
+
## 🤝 Code of Conduct
34
37
35
-
1. Using `MLSysOps framework`. Try it out yourself and let us know your experience. Did everything work well? Were the instructions clear?
36
-
2. Improve or suggest changes to the documentation of the project. Documentation is very important for every project, hence any ideas on how to improve the documentation to make it more clear are more than welcome.
37
-
3. Request new features. Any proposals for improving or adding new features are very welcome.
38
-
4. Find a bug and report it. Bugs are everywhere and some are hidden very well. As a result, we would really appreciate it if someone found a bug and reported it to the maintainers.
39
-
5. Make changes to the code. Improve the code, add new functionalities and make `MLSysOps framework` even more useful.
38
+
By participating in this project, you agree to abide by our [Code of Conduct](../../CODE_OF_CONDUCT.md). Please take a moment to read it.
40
39
41
-
## Opening an issue
40
+
---
41
+
42
+
## ✨ Ways to Contribute
43
+
44
+
We welcome contributions of all kinds, including:
45
+
46
+
- 📖 Improving documentation and fixing typos
47
+
- 💡 Suggesting new features or enhancements
48
+
- 🐛 Reporting bugs
49
+
- 🧪 Writing or improving tests
50
+
- 💻 Fixing issues
51
+
- 🌐 Translating the project
52
+
- 🧱 Improving code structure or consistency
53
+
54
+
---
42
55
43
-
We use Github issues to track bugs and requests for new features.
44
-
Anyone is welcome to open a new issue, which is either related to a bug or a request for a new feature.
56
+
## 🔀 How to Submit a PR
45
57
46
-
### Reporting bugs
58
+
1.**Fork the repository**
59
+
Click the **Fork** button on the top-right of this repo's GitHub page.
47
60
48
-
In order to report a bug or misbehavior in `MLSysOps framework`, a user can open a new issue explaining the problem.
49
-
For the time being, we do not use any strict template for reporting any issues.
50
-
However, in order to easily identify and fix the problem, it would be very helpful to provide enough information.
51
-
In that context, when opening a new issue regarding a bug, we kindly ask you to:
Ensure your code follows existing style guidelines and passes all checks.
76
+
77
+
5.**Commit your changes**
78
+
79
+
```bash
80
+
git commit -m "feat: Add a descriptive message"
81
+
```
82
+
83
+
6.**Push your branch**
84
+
85
+
```bash
86
+
git push origin your-feature-name
87
+
```
88
+
89
+
7.**Open a Pull Request**
90
+
Go to the GitHub page of your fork, and click "Compare & pull request".
91
+
Provide a clear title and description of your changes.
92
+
93
+
---
55
94
56
-
1. A short description of the bug.
57
-
2. The respective logs both from the output and containerd.
58
-
3. Framework's version manifest (either the commit hash or the version manifest file).
59
-
4. The execution environment (CPU architecture, VMM etc.).
60
-
5. Any particular steps to reproduce the issue.
61
-
- Keep an eye on the issue for possible questions from the maintainers.
95
+
## ✍️ Writing Good Commit Messages
62
96
63
-
A template for an issue could be the following one:
97
+
Follow the conventional commit format:
98
+
99
+
```bash
100
+
<type>(scope): short description
64
101
```
65
-
## Description
66
-
An explanation of the issue
67
102
68
-
## System info
103
+
**Examples:**
104
+
105
+
-`feat(docs): add contributing guidelines`
106
+
-`fix(auth): resolve login redirect issue`
107
+
-`chore: update dependencies`
108
+
109
+
**Types:**
110
+
111
+
-`feat` – A new feature
112
+
-`fix` – A bug fix
113
+
-`docs` – Documentation only changes
114
+
-`style` – Changes that do not affect the meaning of the code
115
+
-`refactor` – Code changes that neither fix a bug nor add a feature
116
+
-`test` – Adding missing tests
117
+
-`chore` – Changes to the build process or tools
118
+
119
+
---
120
+
121
+
## 🏷️ Issue Labels
122
+
123
+
Our GitHub issues use the following labels to help contributors find where they can help:
124
+
125
+
-`good first issue` – Great for newcomers!
126
+
-`help wanted` – We need help with this.
127
+
-`bug` – Confirmed bugs.
128
+
-`enhancement` – Feature or improvement requests.
129
+
-`question` – Discussions or clarifications.
130
+
131
+
---
132
+
133
+
## 🌱 Branching Strategy
134
+
135
+
We follow a simple Git branching model:
136
+
137
+
-`main` – Stable, production-ready code.
138
+
-`dev` – Development branch. All features and bug fixes should branch from and merge back into dev.
139
+
140
+
**Example workflow:**
69
141
70
-
- Version:
71
-
- Arch:
72
-
- VMM:
73
-
- ...
142
+
```bash
143
+
# Start from dev
144
+
git checkout dev
145
+
git pull
74
146
75
-
## Steps to reproduce
76
-
A list of steps that can reproduce the issue.
147
+
# Create your feature branch
148
+
git checkout -b feat/component-xyz
77
149
```
78
150
79
-
### Requesting new features
80
-
81
-
We will be very happy to listen from users about new features that they would like to see in `MLSysOps framework`.
82
-
One way to communicate such a request is using Github issues.
83
-
For the time being, we do not use any strict template for requesting new features.
84
-
However, we kindly ask you to mark the issue with the enhancement label and provide a description of the new feature.
85
-
86
-
## Submitting a PR
87
-
88
-
Anyone should feel free to submit a change or an addition to the codebase of `MLSysOps framework`.
89
-
Currently, we use Github's Pull Requests (PRs) to submit changes to `MLSysOps framework`'s codebase.
90
-
Before creating a new PR, please follow the guidelines below:
91
-
92
-
- Make sure that the changes do not break the building process of `MLSysOps framework`.
93
-
- Make sure that all the tests run successfully.
94
-
- Make sure that no commit in a PR breaks the building process of `MLSysOps framework`
95
-
- Make sure to sign-off your commits.
96
-
- Provide meaningful commit messages, describing shortly the changes.
97
-
- Provide a meaningful PR message
98
-
99
-
As soon as a new PR is created the following workflow will take place:
100
-
101
-
1. The creator of the PR should invoke the tests by adding the `ok-to-test` label.
102
-
2. If the tests pass, request from one or more `MLSysOps framework`'s [maintainers](https://github.com/nubificus/MLSysOps framework/blob/main/MAINTAINERS) to review the PR.
103
-
3. The reviewers submit their review.
104
-
4. The author of the PR should address all the comments from the reviewers.
105
-
5. As soon as a reviewer approves the PR, an action will add the appropriate git trailers in the PR's commits.
106
-
6. The reviewer who accepted the changes will merge the new changes.
107
-
108
-
## Labels for the CI
109
-
110
-
We use github workflows to invoke some tests when a new PR opens for `MLSysOps framework`.
111
-
In particular, we perform the following workflows tests:
112
-
113
-
- Linting of the commit message. Please check the [git commit message style](#git-commit-messages) below for more info.
114
-
- Spell check, since `MLSysOps framework` repository contains its documentation too.
115
-
- License check
116
-
- Code linting.
117
-
- Building artifacts for amd64 and aarch64.
118
-
- Unit tests
119
-
- End-to-end tests
120
-
121
-
For a better control over the tests and workflows that run in a PR, we define
122
-
three labels which can be used:
123
-
124
-
-`ok-to-test`: Runs a full CI workflow, meaning all lint tests (commit
125
-
message, spellcheck, license), Code linting, building for x86 and aarch64,
126
-
unit tests and at last end-to-end tests.
127
-
-`skip-build`: Skips the building workflows along with unit and end-to end tests
128
-
running all the linting tests. This is useful when
129
-
the PR is related to docs and it can help for catching spelling errors etc. In
130
-
addition, if the changes are not related to the codebase, running the
131
-
end-to-end tests is not required and saves some time.
132
-
-`skip-lint`: Skips the linting phase. This is particularly useful on draft
133
-
PRs, when we want to just test the functionality of the code (either a bug
134
-
fix, or a new feature) and defer the cleanup/polishing of commits, code, and
135
-
docs to when the PR will be ready for review.
136
-
137
-
**Note**: Both `skip-build` and `skip-lint` assume that the `ok-to-test` label
138
-
is added.
139
-
140
-
## Style guide
141
-
142
-
### Git commit messages
143
-
144
-
Please follow the below guidelines for your commit messages:
145
-
146
-
- Limit the first line to 72 characters or less.
147
-
- Limit all the other lines to 80 characters
148
-
- Follow the [Conventional Commits](https://www.conventionalcommits.org/)
149
-
specification and, specifically, format the header as `<type>[optional scope]:
150
-
<description>`, where `description` must not end with a fullstop and `type`
151
-
can be one of:
152
-
153
-
-*feat*: A new feature
154
-
-*fix*: A bug fix
155
-
-*docs*: Documentation only changes
156
-
-*style*: Changes that do not affect the meaning of the code (white-space,
157
-
formatting, missing semi-colons, etc)
158
-
-*refactor*: A code change that neither fixes a bug nor adds a feature
159
-
-*`perf`*: A code change that improves performance
160
-
-*test*: Adding missing tests
161
-
-*build*: Changes that affect the build system or external dependencies
162
-
(example scopes: gulp, broccoli, `npm`)
163
-
-*ci*: Changes to our CI configuration files and scripts (example scopes:
164
-
`Travis`, `Circle`, `BrowserStack`, `SauceLabs`)
165
-
-*chore*: Other changes that don't modify src or test files
166
-
-*revert*: Reverts a previous commit
167
-
- In case the PR is associated with an issue, please refer to it, using the git trailer `Fixes: #Nr_issue`
168
-
- Always sign-off your commit message
169
-
170
-
Since the MLSysOps framework comprises code written in various programming
171
-
languages we use the following styles for each:
172
-
173
-
### Golang code style
174
-
175
-
We follow `gofmt`'s rules on formatting GO code. Therefore, we ask all
176
-
contributors to do the same. Go provides the `gofmt` tool, which can be used
Depending on your development needs, you may want to build various components or run them locally. Follow the instructions in the respective README files of each module (e.g., mlsysops-cli, agents, etc.) for component-specific development workflows.
21
+
22
+
---
23
+
24
+
## Recommendations
25
+
26
+
- Use a Python virtual environment for CLI or backend development.
27
+
- Use pre-commit to enforce linting and formatting rules (see Contributing Guide).
28
+
- For advanced setup like deploying agents, check relevant module README files under the `agents/` or `mlsysops-cli/` directories.
29
+
30
+
---
31
+
32
+
## Need Help?
33
+
34
+
If you encounter issues during setup, feel free to [open an issue](https://github.com/mlsysops-eu/mlsysops-framework/issues) or refer to the [Developer Guide Index](../developer-guide/index.md).
0 commit comments