Skip to content

Commit 73ab1be

Browse files
nilssottonilssotto
committed
Update README etc.
1 parent da875b9 commit 73ab1be

File tree

4 files changed

+435
-83
lines changed

4 files changed

+435
-83
lines changed

‎CODING_STYLE.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# opsi-configed Coding Style
2+
3+
## Indentation and Formatting
4+
5+
* Use 4 spaces for indentation.
6+
* Use braces for block statements, even if the block only contains a single
7+
statement.
8+
* Place a space before opening parentheses in control statements (`if`,
9+
`for`, `while`, etc.).
10+
* Use a newline after opening and before closing braces for classes, methods,
11+
and control statements.
12+
* Limit the line length to 120 characters for better readability.
13+
14+
## Braces
15+
16+
* Use the "Egyptian brackets" style for braces:
17+
* Place the opening brace on the same line as the declaration or control
18+
statement.
19+
* Place the closing brace on a new line, aligned with the indentation
20+
level of the corresponding opening statement.
21+
22+
### Example:
23+
24+
```java
25+
if (condition) {
26+
// Statements
27+
} else {
28+
// Statements
29+
}
30+
```
31+
32+
## Naming Conventions
33+
34+
### Class and Interface Names
35+
36+
* Use PascalCase (CamelCase with initial uppercase) for class and interface
37+
names.
38+
* Choose meaningful and descriptive names that accurately represent the
39+
purpose or behavior of the class or interface.
40+
* Abstract class should contain `Abstract` in their names (`AbstractTree`).
41+
42+
### Method Names
43+
44+
* Use camelCase for method names (initial lowercase).
45+
* Choose meaningful and descriptive names that accurately represent the
46+
action or behavior performed by the method.
47+
* Use verbs or verb phrases to indicate actions (e.g., `calculateTotal()`,
48+
`getUserByID()`).
49+
50+
### Variable Names
51+
52+
* Use camelCase for variable names (initial lowercase).
53+
* Choose meaningful and descriptive names that accurately represent the
54+
purpose or content of the variable.
55+
* Avoid single-character names except for loop counters (`i`, `j`, `k`).
56+
* Use nouns or noun phrases for variables representing objects or data.
57+
58+
### Constant Names
59+
60+
* Use uppercase with underscores for constant names.
61+
* Separate words in a constant name with underscores (`CONSTANT_NAME`).
62+
* Choose descriptive names that clearly indicate the purpose or value of
63+
the constant.
64+
65+
### Abbreviations
66+
67+
* For abbreviations use uppercase (e.g., `IO`, `URL`, `ID`).
68+
69+
## Code Documentation
70+
71+
* Use Javadoc comments to document classes, interfaces, methods, and variables.
72+
* Provide meaningful descriptions and explanations for the documented elements.
73+
* Include information about the purpose, behavior, parameters, return values,
74+
and exceptions (if applicable) in the Javadoc comments.
75+
76+
## Code Quality and SonarLint
77+
78+
* Follow code quality best practices and adhere to the principles of clean code.
79+
* Utilize SonarLint tool to identify and resolve code bugs, code smells, and
80+
potential vulnerabilities. Configed has its own SonarLint server, which
81+
is used by us and is specifically configured for the project. The Configed
82+
server should be used to adhere to our configured rules.
83+
* Ensure that every commit is free of SonarLint warnings and errors.
84+
85+
By adhering to these coding style conventions and best practices, you can
86+
maintain clean, readable, and consistent Java code for opsi-configed project.
87+

‎CONTRIBUTING.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Contributing to opsi-configed
2+
3+
Thank you for your interest in contributing to the Configed project! We
4+
appreciate your contributions to help improve the project. To ensure a
5+
smooth collaboration, please follow these guidelines when contributing.
6+
7+
## Commit Message Convention
8+
9+
We follow a prefix-based commit message convention to provide clarity
10+
and consistency in our commit messages. The convention is as follows:
11+
12+
```bash
13+
[Prefix]: Short Description
14+
```
15+
16+
### Prefixes
17+
18+
Prefixes are used to categorize commits based on the type of change they
19+
represent. The following prefixes are used in our project:
20+
21+
* **new**: A new feature implementation
22+
* **chg**: Implementation changes
23+
* **dep**: Changes related to deprecated code or functionality
24+
* **rem**: Removal or deletion of code or files
25+
* **fix**: A bug fix
26+
* **sec**: Security-related changes or fixes
27+
28+
## Commit Message Guidelines
29+
30+
Please adhere to the following guidelines when crafting your commit messages:
31+
32+
* Separate the subject line from the body with a blank line.
33+
* Limit the subject line to 50 characters or less and the body to 72 characters
34+
per line.
35+
* Capitalize the subject line and use imperative mood (e.g., "Add", "Fix").
36+
* Do not end the subject line with a period.
37+
* Provide explanatory text in the body to explain what and why, rather than how.
38+
* Include relevant issues by referencing their numbers in the commit message.
39+
* Use the following rules for commit messages:
40+
1. Follow an atomic commit approach, addressing a single logical change in
41+
each commit.
42+
2. Include the original problem description when fixing an issue.
43+
3. Avoid assuming the code is self-explanatory and provide sufficient context.
44+
45+
### Example Commit Message
46+
47+
```
48+
[new] Implement login functionality
49+
50+
This commit adds a new login feature that allows users to authenticate
51+
and access protected resources. It includes the necessary API endpoints,
52+
database schema modifications, and user interface changes.
53+
54+
Fixes #123
55+
```
56+
57+
## Breaking Change
58+
59+
In our project, we follow a specific convention for a committing a breaking
60+
changes to our codebase. This convention helps us maintain a clear and
61+
standardized commit history, making it easier for developers to understand
62+
the nature and impact of changes.
63+
64+
A breaking commit refers to a commit that introduces changes that could
65+
potentially break existing functionality or cause compatibility issues.
66+
These changes are typically significant and may require careful consideration
67+
by other developers who depend on the codebase.
68+
69+
When creating a breaking commit in our project, we include an exclamation
70+
mark (!) symbol at the end of the prefix but before the short description.
71+
This convention is widely adopted within our team and serves as a visual
72+
indicator to quickly identify commits that may introduce compatibilty issues
73+
or break existing functionality.
74+
75+
For instance, if we make a breaking change that modifies a critical function
76+
in our software library, we would write a breaking commit message like
77+
"[chg]! modify function x to improve performance" By adding the exclamation
78+
mark after the "chg" prefix, it becomes immediately apparent that this commit
79+
contains changes with the potential to break existing functionality.
80+
81+
It's important to note that the convention of adding the exclamation mark (!)
82+
symbol after the breaking prefix is specifc to our project. While it may not
83+
be a strict requirement imposed by version control systems or tools like Git,
84+
we have found it to be a valuable practice that improves code comprehension
85+
within our team.
86+
87+
## Coding Style and Code Analysis
88+
89+
* All code changes must adhere to the project's [coding style guidelines](CODING_STYLE.md).
90+
* We use SonarLint tool to identify and resolve bugs, code smells, and other
91+
issues.
92+
* Ensure that every commit has no SonarLint warnings or issues.
93+
94+
## Merge Requests and Issues
95+
96+
In our project, we use merge requests and issues to facilitate collaboration
97+
and track progress. Understanding when to use each can help streamline the
98+
development process.
99+
100+
### Merge Requests
101+
102+
Merge requests are used when you have completed a task or made changes to the
103+
code that need to be reviewed and merged into the `main` branch. They are
104+
typically used for the following scenarios:
105+
106+
* Implementing new features
107+
* Fixing bugs
108+
* Refactoring code
109+
* Making significant changes to the project
110+
111+
When creating a merge request, make sure to provide a clear and concise
112+
description of the changes made, along with any relevant information or
113+
context. This helps reviewers understand the purpose and impact of the changes
114+
and enables a smooth review process.
115+
116+
### Issues
117+
118+
Issues are used to track and discuss specific tasks, enhancements, or bugs
119+
in the project. They are a way to document and organize work that needs to
120+
be done. Issues can be used for the following purposes:
121+
122+
* Reporting bugs or unexpected behavior
123+
* Discussing and planning new features or enhancements
124+
* Tracking tasks and assignments
125+
126+
When creating an issue, provide a descriptive title and a detailed description
127+
of the problem or task. Include any relevant information, such as steps to
128+
reproduce a bug or specifications for a new feature. This helps in providing
129+
context and ensures that everyone involved understands the purpose and scope
130+
of the issue.
131+
132+
It's a good practice to reference the relevant issues in your merge requests
133+
by mentioning the issue number or using the "Closes" keyword. This helps in
134+
establishing the link between the work being done and the associated issue,
135+
making it easier to track the progress and close the issue when the changes
136+
are merged.
137+
138+
Remember, clear and informative merge requests and well-documented issues
139+
contribute to effective collaboration and ensure that the development process
140+
runs smoothly.
141+
142+
## Branch Strategy
143+
144+
### Branch Types
145+
146+
* **`main` branch**: The `main` branch serves as the main integration
147+
branch for ongoing development work. It is where individual feature
148+
branches or bug fix branches are merged in preparation for the next
149+
release. The `main` branch may contain features and bug fixes that
150+
are still being tested and refined.
151+
152+
When starting work on a new feature or bug fix, create a new branch from
153+
the `main` branch. Once the changes are completed and tested, they can
154+
be merged back into the `main` branch.
155+
156+
### Creating Branches
157+
158+
When working on a new feature, bug fix, or any other code change, follow
159+
this branch naming convention:
160+
161+
```
162+
<type>/<short-description>
163+
```
164+
165+
* `<type>`: Use one of the following prefixes to indicate the type of the branch:
166+
* `feat`: Feature implementation
167+
* `fix`: Bug fix
168+
* `ref`: Code refactoring
169+
* `docs`: Documentation changes
170+
* `style`: Code style changes
171+
* `perf`: Performance improvements
172+
* `ci`: Continuous Integration configuration
173+
* `sec`: Security-related changes or fixes
174+
* `<short-description>`: A brief description of the changes being made.
175+
176+
Example: `feat/user-authentication`, `fix/file-upload-bug`
177+
178+
## Workflow
179+
180+
1. Create a new branch for the issue or task you are working on, based on
181+
the `main` branch.
182+
2. Make the necessary changes, additions, or fixes in your branch.
183+
3. Commit your changes following the commit message guidelines, including
184+
relevant issues.
185+
4. Push your branch to the remote repository.
186+
5. Create a merge request to propose your changes for review.
187+
6. Discuss and iterate on your code changes through comments on the
188+
merge request.
189+
7. Once the changes are approved, they will be merged into the `main` branch.
190+
191+
## Discussion and Communication
192+
193+
All discussions and communication related to the project should be conducted
194+
in English. This helps to ensure clear and effective communication among
195+
contributors from different backgrounds.
196+
197+
We appreciate your contribution to Configed and adherence to these guidelines!
198+
By following these guidelines and the established workflow, we can maintain
199+
a collaborative and efficient development process.
200+
201+
Please reach out to us if you have any questions or need further assistance.
202+
203+
Thank you,
204+
205+
Configed Team

‎DEVELOPMENT_GUIDE.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# opsi-configed Development Guide
2+
3+
This development guide provides instructions on how to set up your development
4+
environment for the project and describes the recommended tools and resources
5+
for development.
6+
7+
## Development Environment Setup
8+
9+
To get started with development for the project, follow these steps:
10+
11+
1. Install [VSCode](https://code.visualstudio.com/) as Integrated Development
12+
Environment (IDE). Any other IDE is a viable option, however, we highly
13+
recommend using VSCode for its extensive support and compatibility with our
14+
development setup.
15+
2. Clone the project repository to your local machine using the following
16+
command:
17+
18+
```
19+
git clone repository
20+
```
21+
22+
3. Install the [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
23+
extension in VSCode. This extension allows you to develop inside a Docker
24+
container seamlessly.
25+
4. Open the project folder in VSCode. If you have the Remote - Containers
26+
extension installed, you will see a popup recommending to reopen the project
27+
in a container. Click on "Reopen in Container" to start the development
28+
environment within the Docker container.
29+
5. If you are using Windows, you will need to modify the Docker container
30+
script to accommodate any additional tools or configurations required for
31+
the Windows environment. For Windows environment configuration instructions,
32+
please refer to the [Windows Environment Configuration](#windows-environment-configuration)
33+
section.
34+
6. The Docker container is pre-configured with all the necessary tools and
35+
extensions needed for development. It provides a consistent and isolated
36+
environment for all contributors.
37+
38+
## Development Workflow
39+
40+
Once your development environment is set up, you can follow this workflow:
41+
42+
1. Make sure you are developing inside the Docker container. This ensures that
43+
your development environment is consistent with other contributors.
44+
2. Create a new branch for your changes. Use a descriptive branch name that
45+
reflects the purpose of your changes. Follow the [branch creation rules](CONTRIBUTING.md#creating-branches)
46+
described in the contributing guidelines.
47+
3. Write your code following the coding style guidelines described in the [CODING_STYLE.md](CODING_STYLE.md)
48+
file.
49+
4. Commit your changes regularly in small, logical units. Follow the
50+
[commit message conventions](CONTRIBUTING.md#commit-message-convention)
51+
described in the contributing guidelines.
52+
5. Push your branch to the remote repository when you are ready to submit
53+
your changes.
54+
6. Create a merge request to propose your changes for review. Provide a clear
55+
and detailed description of the changes, referencing any related issues or
56+
relevant information.
57+
7. Collaborate with other contributors and address any feedback or comments
58+
received during the review process.
59+
8. Once your changes have been reviewed and approved, they will be merged into
60+
the ```main``` branch.
61+
62+
## Windows Environment Configuration
63+
64+
To configure the development environment in Windows, follow these additional
65+
steps:
66+
67+
1. Install MobaXterm and start it.
68+
2. Configure X server: Go to Settings -> X11 (tab) -> set X11 Remote Access to
69+
"full".
70+
3. Uncomment/comment the necessary lines in the devcontainer.json file to
71+
enable X server support.
72+
4. Set the `DISPLAY` environment variable in the devcontainer.json file to `host
73+
docker.internal:0`.
74+
5. Disable the "mounts" section in the devcontainer.json file.
75+
6. Reopen the project in the devcontainer.
76+
7. Start the configuration server by running the following commands in the
77+
terminal within the devcontainer:
78+
```bash
79+
mvn package
80+
java -jar target/configed-<VERSION>-jar-with-dependencies.jar
81+
```
82+
83+
These steps ensure that the necessary configurations are in place for running
84+
the project within the Docker container on a Windows environment using
85+
MobaXterm and X server settings.
86+
87+
Note: Make sure to replace <VERSION> with the appropriate version number of
88+
the Configed project.
89+
90+
(Source: https://stackoverflow.com/a/36190462)
91+
92+
## Conclusion
93+
94+
Following the guidelines and using the recommended tools, such as VSCode with
95+
the Remote - Containers extension, will help ensure a smooth and consistent
96+
development experience. The integration with Docker provides an isolated and
97+
pre-configured development environment, eliminating the need for each
98+
contributor to set up their own local environment.
99+
100+
If you have any questions or encounter any issues during the development
101+
process, feel free to reach out to the project maintainers for assistance.
102+
103+
Happy coding!

0 commit comments

Comments
 (0)