Skip to content

Commit 32ff0c0

Browse files
JuliaJakubcovaJuliaJakubcova
authored
Merge pull request #90 from touchlab/jj/building-and-contributing-docs
Add BUILDING and CONTRIBUTING docs, add more sections to templates.
2 parents cccfef7 + 64a30a0 commit 32ff0c0

File tree

4 files changed

+138
-8
lines changed

4 files changed

+138
-8
lines changed

‎.github/ISSUE_TEMPLATE.md‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,40 @@
1+
## Summary
12

2-
<!--**Issue Labels**
3+
<!--- Sum up what this issue is about -->
34

4-
While not necessary, you can help organize our issues by labeling this issue when you open it. To add a label automatically, simply [x] mark the appropriate box below:
5+
## Details
6+
7+
<!--- Provide detailed information about the issue, the more specific you are, the better -->
8+
9+
## Reproduction
10+
11+
<!--- Provide steps for reproduction, if relevant, provide a link to a minimal sample project -->
12+
13+
## Expected result
14+
15+
<!--- Explain what the behavior after fixing this issue should be like -->
16+
17+
## Current state
18+
19+
<!--- Describe the incorrect behavior you are encountering -->
20+
21+
## Possible Fix
22+
23+
<!--- If you have any suggestions or ideas about the reason for this bug, mention them here -->
24+
25+
## Screenshots
26+
27+
<!--- If relevant, include screenshots or videos, especially useful with UI bugs / suggestions -->
28+
29+
<img width="250" alt="fix in action" src="https://media.makeameme.org/created/yes-it-works.jpg">
30+
31+
## Issue Labels
32+
33+
<!--- While not necessary, you can help organize our issues by labeling this issue when you open it. To add a label automatically, simply [x] mark the appropriate box below: -->
534

635
- [ ] has-reproduction
736
- [ ] feature
837
- [ ] blocking
938
- [ ] good first issue
1039

11-
To add a label not listed above, simply place `/label another-label-name` on a line by itself.
12-
-->
40+
<!--- To add a label not listed above, simply place `/label another-label-name` on a line by itself. -->

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
1+
<!--- [Issue-XYZ] Add issue number and title to Title above -->
12

2-
<!--**Pull Request Labels**
3+
<!-- Add issue link -->
4+
Issue: https://github.com/touchlab/xcode-kotlin/issues/[issue number]
35

4-
While not necessary, you can help organize our pull requests by labeling this issue when you open it. To add a label automatically, simply [x] mark the appropriate box below:
6+
## Summary
7+
<!--- Copy summary from issue link or write a shortened description of it -->
8+
9+
## Fix
10+
<!-- What did you do to fix the issue? -->
11+
12+
## Pull Request Labels
13+
14+
<!--- While not necessary, you can help organize our pull requests by labeling this issue when you open it. To add a label automatically, simply [x] mark the appropriate box below: -->
515

616
- [ ] has-reproduction
717
- [ ] feature
818
- [ ] blocking
919
- [ ] good first review
1020

11-
To add a label not listed above, simply place `/label another-label-name` on a line by itself.
12-
-->
21+
<!--- To add a label not listed above, simply place `/label another-label-name` on a line by itself. -->

‎BUILDING.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Building
2+
3+
The xcode-kotlin plugin is written in **Kotlin**. It uses
4+
[Kotlin/Native](https://kotlinlang.org/docs/native-overview.html) for compiling Kotlin code to native binaries.
5+
6+
Building environment: **IntelliJ IDEA**
7+
8+
9+
## Libraries
10+
11+
- [kotlinx-cli](org.jetbrains.kotlinx:kotlinx-cli) - a generic command-line parser used to create user-friendly and flexible command-line interfaces
12+
- [kotlinx-serialization-json](https://kotlinlang.org/docs/serialization.html) - JSON serialization for Kotlin projects
13+
- [kotlinx-coroutines](https://github.com/Kotlin/kotlinx.coroutines) - library support for Kotlin coroutines with multiplatform support
14+
- [Kermit](https://github.com/touchlab/Kermit) - logging utility with composable log outputs
15+
16+
## Project structure
17+
18+
In the `command` directory the commands users can call are implemented: *info*, *install*, *sync* and *uninstall*.
19+
Each has an `execute` function with the implementation, that calls classes like `Installer` or `Uninstaller`.
20+
- `BaseXcodeListSubcommand` is an abstract class overriden by the following classes (Info, Install and Sync). It
21+
provides them with a protected method for getting a list of Xcode installations.
22+
- `Info` checks for an available update or if the plugin is not yet installed, writes information about the plugin to
23+
the console, such as installed and bundles versions, if Language spec and LLDB is installed and if LLDB for Xcode has
24+
been initialized, also Xcode version and the plugin compatibility.
25+
- `Install` checks for current version and offers updating, reinstalling or downgrading if it is already installed or
26+
installs it if not.
27+
- `Sync` adds IDs of Xcode installations to the currently installed Xcode Kotlin plugin.
28+
- `Uninstall` uninstalls the plugin.
29+
30+
In the `util` directory are, as the name suggests, util classes.
31+
- `Console` provides convenience functions for prompting user for confirmation or value and printing output to the
32+
console.
33+
- `CrashHelper` provides functions for logging, capturing and uploading errors (crash reports).
34+
- `File` is a class for holding a file path and providing methods for working with a file.
35+
- `Path` holds a string value and provides methods for appending and deleting path components and resolving sym links.
36+
It also provides convenience methods for creating Paths to home, work, binary and data directories in its companion
37+
object.
38+
- `PropertyList` is a class for converting to and from Swift classes.
39+
- `Shell` is a helper for executing shell tasks.
40+
41+
The other classes in the `cli` directory are mainly managers and helpers that provide methods for installing and
42+
uninstalling various parts of the plugin.
43+
- `Installer` has an `installAll` method for calling install on all the managers.
44+
- `LangSpecManager` provides `install` and `uninstall` methods and `isInstalled` check for the Kotlin.xclangspec.
45+
- `LLDBInitManager` provides `install` and `uninstall` methods and `isInstalled` and `sourcesMainLlvmInit` checks for
46+
the LLDB init.
47+
- `PluginManager` provides `install`, `sync` and `uninstall` methods,`isInstalled` check and `bundledVersion`,
48+
`installedVersion` and `targetSupportedXcodeUUIds` properties for the plugin.
49+
- `Uninstaller` has an `uninstallAll` method for calling uninstall on all the managers.
50+
- `XcodeHelper` provides methods for interacting with Xcode installations: `ensureXcodeNotRunning` to check and
51+
optionally shut down running Xcode instances, `allXcodeInstallations` that returns a list of found Xcode installations,
52+
`addKotlinPluginToDefaults` for adding a plugin to allowed list in Xcode defaults and `removeKotlinPluginFromDefaults`
53+
for removing it.
54+
55+
In `build.gradle` there are two gradle tasks added: `assembleReleaseExecutableMacos` for building a universal macOS
56+
binary and `preparePlugin` for preparing the plugin and language specification to build dir.
57+
58+
This project uses Object classes instead of dependency injection (DI) because of its small size.

‎CONTRIBUTING.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# How to contribute
2+
3+
In the first place, thank you for thinking about contributing to **xcode-kotlin**!
4+
Here you can find a set of guidelines for pitching in.
5+
6+
## Questions
7+
8+
If you have any questions, please, contact us in the Kotlin [Community Slack](https://kotlinlang.slack.com/) in
9+
[the #touchlab-tools channel](https://kotlinlang.slack.com/archives/CTJB58X7X). To join the Kotlin Community Slack,
10+
[request access here](http://slack.kotlinlang.org/).
11+
12+
For direct assistance, please [reach out to Touchlab](https://touchlab.co/contact-us/) to discuss support options.
13+
14+
## Set up environment
15+
16+
For instructions on how to set up your environment and run the project, refer to the
17+
[README](https://github.com/touchlab/xcode-kotlin/blob/main/README.md) and
18+
[BUILDING](https://github.com/touchlab/xcode-kotlin/blob/main/BUILDING.md).
19+
20+
## Create an issue
21+
22+
If you have stumbled across a bug or have a good feature suggestion / enhancement, you can create an
23+
[issue](https://github.com/touchlab/xcode-kotlin/issues), but please don't mistake it for the general helpline. You can
24+
get answers for general questions in Slack. Please, fill in carefully all the info the issue template suggests. It will
25+
save us time when investigating the problem. There might be a bit of a delay until we get to your ticket, so we ask for
26+
your patience.
27+
28+
## Submit a merge request
29+
30+
If you wish to participate in submitting code changes, to start with, you can look for issues tagged with **good first
31+
issue**. In case you feel like making significant changes or adding features, please discuss with the team first before
32+
you start working on it, to ensure we are on the same page. When your fix / feature is ready, create a merge request
33+
using the pull request template and fill in as much information as possible. All merge requests need to pass a code
34+
review from our team member, and subsequently they are approved or rejected with a reason. It might take some time
35+
before we get to your merge request, but don’t worry, it didn't get lost.

0 commit comments

Comments
 (0)