Skip to content

Commit 76d4837

Browse files
narknonBuckminsterfullerene02UE4SS
authored
docs: Add contributing.md, PR guidelines, and upgrade guide for migration notices (#838)
* docs: Add contributing.md for contributing and PR guidelines; add upgrade/migration guide * Minor changes to contributing add upgrade problem issue template Add extra non-code files in repo root to paths to ignore in pr build-ci Update docs/contributing.md Co-authored-by: UE4SS <91646798+UE4SS@users.noreply.github.com> Remove coc from ci check * Further clarification for reporting issues * Further clarification for general requirements --------- Co-authored-by: Buckminsterfullerene02 <bobby45900@gmail.com> Co-authored-by: UE4SS <wildbrim@hotmail.com>
1 parent a2d8c5d commit 76d4837

5 files changed

Lines changed: 238 additions & 2 deletions

File tree

‎.github/ISSUE_TEMPLATE/upgrade_problem.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: Upgrade Problem
3+
about: Report issues encountered upgrading your mod to a new version
4+
title: "[Upgrade Problem]"
5+
labels: 'upgrade problem'
6+
---
7+
8+
**Current UE4SS Version**
9+
<!-- The version you are upgrading from. -->
10+
11+
12+
**Target UE4SS Version**
13+
<!-- The version you are upgrading to. -->
14+
15+
16+
**Describe the Problem**
17+
<!-- A clear and concise description of what the problem is. -->
18+
19+
20+
**Logs and Configuration**
21+
<!-- Attach any relevant logs or configuration files that could help identify the problem. -->
22+
23+
24+
**Screenshots**
25+
<!-- If applicable, add screenshots to help explain your problem. -->
26+
27+
28+
**Desktop (please complete the following information):**
29+
- OS: [e.g. Win10, Win11]
30+
31+
32+
**Additional Context**
33+
<!-- Add any other context about the problem here. -->

‎.github/workflows/ue4ss-ci.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ on:
1111
- 'main'
1212
paths-ignore:
1313
- 'README.md'
14+
- 'LICENSE'
15+
- 'CNAME'
1416
- '.github/workflows/pushdocs.yml'
1517
- '.github/pull_request_template.md'
1618
- '.github/ISSUE_TEMPLATE/**'

‎docs/SUMMARY.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
[Home](./README.md)
44
[Installation](./installation-guide.md)
5-
<!-- [Contributing](./contributing.md) -->
5+
[Contributing](./contributing.md)
6+
[Update Migration Guide](./upgrade-guide.md)
67

78
---
89

‎docs/contributing.md‎

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,136 @@
1-
# Contributing
1+
# Contributing to RE-UE4SS
2+
3+
Thank you for taking the time to contribute!
4+
5+
All types of contributions are encouraged and valued. This guide outlines the process and guidelines for contributing to the project.
6+
7+
## Table of Contents
8+
9+
- [Reporting issues](#reporting-issues)
10+
- [Pull Request Guidelines](#pull-request-guidelines)
11+
- [Development Workflow](#development-workflow)
12+
- [Code Style Guidelines](#code-style-guidelines)
13+
- [Commit Message Guidelines](#commit-message-guidelines)
14+
- [Upgrade Guidelines](#upgrade-guidelines)
15+
- [License](#license)
16+
17+
## Reporting Issues
18+
19+
Before you ask a question, it is best to search for existing [issues](https://github.com/UE4SS-RE/RE-UE4SS/issues) and read the available [documentation](https://docs.ue4ss.com/).
20+
21+
If you still need clarification:
22+
- Open an [issue](https://github.com/UE4SS-RE/RE-UE4SS/issues) using the correct template
23+
- Provide as much context as you can about what you're experiencing
24+
- Provide project and platform versions (OS, etc.)
25+
- If the issue is build related, provide toolchain information (compiler version, etc.)
26+
- Provide UE4SS.log whenever it's available, even if it doesn't seem useful
27+
28+
> **Security Issues**: Never report security-related issues, vulnerabilities or bugs including sensitive information to the issue tracker. Instead, please email sensitive bugs to <security@ue4ss.com>.
29+
30+
## Pull Request Guidelines
31+
32+
### General Requirements
33+
34+
1. Before submitting a PR, please ensure your changes have been tested on:
35+
- At least one Unreal Engine version between 4.11 and 4.25 (the version where UProperty was replaced by FProperty)
36+
- At least one version after 4.25, preferably UE 5.1 or newer
37+
38+
2. All PRs must include:
39+
- A clear description of the changes
40+
- Steps to reproduce the issue being fixed (if applicable)
41+
- Code to reproduce the problem it fixes or feature it adds
42+
- Any relevant test cases or examples
43+
- Updates to the [Changelog.md](/assets/Changelog.md) file with relevant changes
44+
45+
3. Code should be well-documented and follow the existing style conventions of the repository.
46+
47+
## Development Workflow
48+
49+
1. Fork the repository
50+
2. Create a new branch for your feature or bug fix
51+
3. Implement your changes
52+
4. Run the appropriate tests for your changes
53+
5. Update the documentation if necessary
54+
6. Submit a pull request
55+
56+
## Code Style Guidelines
57+
58+
### UEPseudo Code
59+
60+
- Code in UEPseudo should match Unreal Engine's formatting and style conventions
61+
- When implementing code directly from Unreal Engine, maintain the original style
62+
- Any deviations or fixes from the original UE code should be enclosed between these comments:
63+
```cpp
64+
// RE-UE4SS FIX (Contributor initials or username): [explanation of why the fix is needed]
65+
// Modified code goes here
66+
// RE-UE4SS FIX END
67+
```
68+
69+
70+
### Main Repository Code
71+
72+
- All code in the main repository should have `clang-format` run against it before submission
73+
- Follow the existing code style of the repository for consistency
74+
- Use meaningful variable and function names
75+
- Include comments for complex logic or non-obvious implementations
76+
77+
## Commit Message Guidelines
78+
79+
- We favor [Conventional Commits](https://www.conventionalcommits.org/) format for all commit messages.
80+
```
81+
<type>[optional scope]: <description>
82+
83+
[optional body]
84+
85+
[optional footer(s)]
86+
```
87+
- Common types include: feat, fix, docs, style, refactor, test, chore
88+
- Reference issue numbers in your commit messages when applicable
89+
- Keep commits focused on a single logical change
90+
91+
## Upgrade Guidelines
92+
93+
We maintain an upgrade guide to track breaking changes and help users migrate between versions.
94+
95+
### For Contributors
96+
97+
When making breaking changes to the API:
98+
99+
1. You must document all breaking changes in `/docs/upgrade-guide.md`, including:
100+
- A clear description of what changed
101+
- The reason for the change
102+
- Code examples showing the old way vs. the new way
103+
- Any special migration steps
104+
105+
2. Breaking changes should follow these principles:
106+
- Minimize the impact on existing code
107+
- Provide deprecation warnings where possible before removal
108+
- Consider backward compatibility or transitional APIs
109+
- Clearly communicate the change through version numbering (follow semver)
110+
111+
3. When submitting a PR with breaking changes:
112+
- Explicitly tag it with `breaking-change` in the PR title
113+
- Update the Changelog with a "Breaking Changes" subsection
114+
- Reference the PR in the upgrade guide
115+
116+
### For API Users
117+
118+
- The `/docs/upgrade-guide.md` file contains version-by-version migration instructions
119+
- Each major and minor version has its own section detailing changes
120+
- Always review the upgrade guide before updating to a new version
121+
- The guide includes code examples for adapting to API changes
122+
123+
The upgrade guide is organized chronologically with the most recent version at the top, making it easy to follow incremental upgrades.
124+
125+
## License
126+
127+
### RE-UE4SS License
128+
By contributing to RE-UE4SS, you agree that your contributions will be licensed under the [MIT licence](https://github.com/UE4SS-RE/RE-UE4SS/blob/main/LICENSE)
129+
130+
### UEPseudo Code Licensing
131+
UEPseudo code is subject to Epic Games' licensing terms.
132+
133+
Thank you for helping improve RE-UE4SS!
134+
135+
## Attribution
136+
This guide is based on the [contributing.md](https://contributing.md/generator)!

‎docs/upgrade-guide.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# RE-UE4SS Upgrade Guide
2+
3+
This document provides detailed guidance for upgrading between versions of RE-UE4SS. Each section covers a specific version upgrade and describes breaking changes, deprecations, and the steps required to migrate your code successfully.
4+
5+
## Version 3.x to 4.x
6+
7+
> **Released:** [TBD]
8+
> **PR:** [Link to PR when available]
9+
10+
### Breaking Changes
11+
12+
#### FString API Changes
13+
14+
##### `GetCharArray()` Behavior Change
15+
16+
**What Changed:**
17+
The `GetCharArray()` method now returns the actual array instead of a pointer to characters.
18+
19+
**Before (v3.x):**
20+
```cpp
21+
// Returned a character pointer
22+
auto GetCharArray() const -> const CharType*;
23+
```
24+
25+
**After (v4.x):**
26+
```cpp
27+
// Returns the array itself
28+
FORCEINLINE DataType& GetCharArray() { return Data; }
29+
FORCEINLINE const DataType& GetCharArray() const { return Data; }
30+
31+
// Use operator* for character pointer access
32+
FORCEINLINE const TCHAR* operator*() const { return Data.Num() ? Data.GetData() : TEXT(""); }
33+
```
34+
35+
**Migration Steps:**
36+
37+
1. For character pointer access (previously `GetCharArray()`):
38+
```cpp
39+
// Old
40+
const TCHAR* ptr = myString.GetCharArray();
41+
42+
// New
43+
const TCHAR* ptr = *myString;
44+
```
45+
46+
2. For array access (previously `GetCharTArray()`):
47+
```cpp
48+
// Old
49+
TArray<TCHAR>& arr = myString.GetCharTArray();
50+
51+
// New
52+
TArray<TCHAR>& arr = myString.GetCharArray();
53+
```
54+
55+
### Deprecations
56+
57+
- `GetCharTArray()` is now deprecated but still available for compatibility.
58+
It forwards to `GetCharArray()` and will be removed in a future version.
59+
60+
## Reporting Migration Issues
61+
62+
If you encounter problems while upgrading, please:
63+
64+
1. Check the [open issues](https://github.com/UE4SS-RE/RE-UE4SS/issues) for similar reports
65+
2. Create a new upgrade problem issue if your issue hasn't been reported

0 commit comments

Comments
 (0)