xref: /nina/CONTRIBUTING.md (revision 19d8f97f)
1# Contributing
2
3Thank you for considering a contribution to NINA!
4There are many areas where you can contribute, ranging from improving the documentation, writing tutorials, submitting bugs or even writing code for new features inside NINA itself.
5When contributing code or documentation to this repository, please first discuss your plans via an issue, discord or mail with the repo owners, before making a change
6
7# Table of Contents
8[TOC]
9
10# Bug Reporting
11
12If you encounter a bug with N.I.N.A. you can report this via the [issue tracker](https://bitbucket.org/Isbeorn/nina/issues?status=new&status=open)
13
14## Checklist
151. Ensure that the problem still persists on the latest version
162. If the problem still persists, check the issue tracker if there is already an issue open for it
17  * An issue for your problem exists
18    * Check that this issue describes the exact same issue that you are having
19    * Add all information that you have to the issue. Just adding "me too" won't help us much to resolve it.
20    * The more info is available for an issue, the better and faster we can track down the root cause and fix it!
21  * If no issue is already existing create a new one
22
23## What to include
24
25For reporting bugs please use the following guideline to describe the problem:
26
27```
28[ ] Is the issue reproducible?
29[ ] Are you running the latest version?
30[ ] Are all prerequisites that are mentioned inside the manual met?
31
32# Description #
33
34<Put a short description about the issue here>
35
36# Steps to Reproduce #
37* <Step 1>
38* <Step 2>
39* <and so on>
40
41## Expected behaviour ##
42<describe what should happen>
43## Actual behaviour ##
44<describe what actually happened>
45```
46
47Also attach your log file of that session (if applicable), which can be found inside %localappdata%\NINA\Logs
48
49# Contributing documentation
50
51* Documentation is maintained separately in a different [repository](https://bitbucket.org/Isbeorn/nina.docs/src)
52* For a detailed guide on how to contribute to the documentation go to [N.I.N.A.'s documentation contributing guide](https://bitbucket.org/Isbeorn/nina.docs/src/develop/CONTRIBUTING.md)
53
54# Contributing code
55
56## Quick Start
571. Fork the repository
582. Add your changes
593. Check that unit tests are passing
604. Make sure no unnecessary files are accidentally checked in.
615. Add a short description about your changes to the correct section inside "RELEASE_NOTES.md"
626. Push the change to your forked repository using a good commit message
637. Submit a pull request
648. During the pull requests there will be discussions and constructive feedback.
65   Required changes that might be requested during this phase have to be implemented.
66   Once this is done, the pull request can be merged.
67
68## Coding rules
69
70* Always be backwards compatible when having some major rework of a module (e.g. settings change)
71* Follow clean code guidelines. There are many resources about this topic available online.
72* Try to unit test your code
73
74## Branching model
75
76This project is utilizing a standard git flow where it has the following branches
77* master: all officially released code
78* hotfix/<hotfixname>: used to fix critical issues inside master
79* release/<version>: when preparing a release with new features a temporary release branch is created for that new release
80* bugfix/<bugfixname>: issues that are found during a release will be fixed here
81* develop: a general develop branch that will contain unreleased new features
82* feature/<featurename>: new features that will be developed and merged to the develop branch
83
84[A more in-depth guide about this model can be found here](https://nvie.com/posts/a-successful-git-branching-model/)
85
86## Versioning in N.I.N.A.
87
88N.I.N.A. utilizes the versioning scheme MAJOR.MINOR.PATCH.CHANNEL|BUILDNRXXX
89There is currently no automation used and versions are maintained manually.
90
91MAJOR version increases for big changes, like changing technologies etc.
92
93MINOR version will increase for every new released version
94
95PATCH version is reserved to apply Hotfixes to a released versions
96
97CHANNEL|BUILDNR will not be displayed for Released versions, as these are only used to identify Release, RC, Beta and Develop versions
98
99CHANNEL consists of the following values:
100* 1: Nightly
101* 2: Beta
102* 3: Release Candidate
103* 9: Release
104
105BUILDNR should be incremented each nightly build (only in develop,beta and rc versions) by using 3 digits.
106
107Examples:
108Release: 1.8.0.9001             (Displayed as "1.8")
109Release: 1.8.1.9001             (Displayed as "1.8 HF1")
110Release Candidate: 1.8.0.3001   (Displayed as "1.8 RC1")
111Beta: 1.8.0.2004                (Displayed as "1.8 BETA4")
112Develop: 1.8.0.1022             (Displayed as "1.8 NIGHTLY #022")
113
114## Database enhancements
115
116N.I.N.A. uses an SQLite database to store various data. The database is located inside %LOCALAPPDATA%\NINA\NINA.sqlite.
117This database will be automatically created by the EntityFramework based on the files inside <SolutionDir>\NINA\Database\Initial and <SolutionDir>\NINA\Database\Migration
118* Files inside "Initial" folder will be called when the database needs to be created from scratch.
119	* Do not alter these files! Changes here won't get applied for an existing database (e.g. from a previous version)
120	* In case additions have to be made to the database, add a new migration file as described below
121* Files inside migration will be called depending on the current version that is returned via "PRAGMA user_version" of the existing database
122	* The migration is kept simple and follows a naming convention. The migration .sql file matches the version it should migrate to. (Files are named like "1.sql", "2.sql" etc.)
123	* This requires that the same user_version is set as the file name specifies inside the file (e.g. "1.sql" must contain a "PRAGMA user_version = 1;" statement)
124	* Only those files where the version is greater than the current database user_version will be executed
125* During migration the foreign key constraints are deactivated, for easier data manipulation. Be cautious to not corrupt data that way!
126* After a migration a VACUUM will be performed
127
128## Setting up the developer environment
129
130* Install Visual Studio Community 2017 or better
131* External dependencies are automatically installed via nuget (except Camera vendor DLLs)
132* External Camera Vendor SDK DLLs have to be manually put inside the project to \NINA\External\ &lt;x64 and x32&gt;\
133    * To get Canon and Nikon DLLs you have to register as a developer for canon and nikon separately on their websites
134	* Altair SDK: reach out to AltairAstro. They can provide you with their sdk. Contact details at https://cameras.altairastro.com/
135	* ASI SDK: SDK is available at https://astronomy-imaging-camera.com/software-drivers section "For Developers"
136	* Atik SDK: SDK is available at https://www.atik-cameras.com/downloads/
137	* ToupTek SDK: SDK is available at http://www.touptek.com/upload/download/toupcamsdk.zip
138	* QHYCCD SDK: Instructions for integrating the QHYCCD SDK can be found in `NINA\Utility\CameraSDKs\QHYCCD\README.md`
139	* FLI SDK: Instructions for integrating the FLI SDK can be found in `NINA\Utility\CameraSDKs\FLI\README.md`
140    * Due to licensing of those files, they must not be put into a public repository
141* Recommended Visual Studio Extensions:
142    * [CodeMaid](http://www.codemaid.net/): A code cleanup Utility
143    * [XAML Styler](https://github.com/Xavalon/XamlStyler/) A XAML style formatter
144    * [MarkdownEditor](https://github.com/madskristensen/MarkdownEditor) To edit Markdown and auto generate HTML files
145* (Optional) To be able to build the setup projects you need to install [WiX](http://wixtoolset.org/) and their [Visual Studio plugin](https://marketplace.visualstudio.com/items?itemName=RobMensching.WixToolsetVisualStudio2017Extension)
146
147## Automated Unit Tests (AUT)
148
149* The project is using the [NUnit unit-testing framework](https://nunit.org/) to write and run AUTs
150* Additionally to write easy to read assertions [Fluent Assertions](https://fluentassertions.com/) are used
151  * These might seem verbose at first, but they really help reading and understanding the assertions
152* For detailed information about how to use these frameworks please go to their respective homepages
153
154## Running AUTs in Visual Studio
155
156* First double check that your processor architecture for AUTs is set to x64
157  * Test -> Test Settings -> Processor Architecture for AnyCPU Projects -> x64
158  * You also might need to uncheck and re-check "Keep Test Execution Engine Running" for this setting change to become active
159* Prior to running the tests, the project configuration should be set to [Debug][x64]
160* Activate the test explorer
161  * Test -> Windows -> Test Explorer
162* Inside the test explorer you will see all detected AUTs (after building the project)
163* To run all AUTs simply click on "Run All"
164* You can also run and/or debug single AUTs by right clicking inside the respective method and selecting "Run Test" or "Debug Test"
165
166## Pull Requests
167
168* Before making large changes, that will change existing patterns or disrupt ongoing features, please first discuss this via an issue or in discord, before starting to work on the changes! This way we can make sure, that it is the proper time for this change.
169* Make sure that only relevant changes are inside the pull request
170* Validate that all unit tests are sill passing
171* Test your changes *thoroughly* and give a short overview on how you tested your changes in the pull request's description
172* Add yourself to the AUTHORS file, so you will be given proper credit!
173* Create **one pull request per feature/fix**
174* Create your pull requests for new features only against the **develop** branch
175  * Only critical Hotfixes may be created against *master* branch and require a new PATCH version as described in [Versioning in N.I.N.A.]
176
177* Fill out the pull request description template
178
179```
180What is the purpose of this Pull Request?
181
182How were the changes tested?
183
184Are there relevant Issues in the tracker that this PR will fix?
185
186Screenshots
187
188Notes
189```
190
191## NINASetupBundle Prerequisites
192
193* To provide release notes for the setup bundle, there is a build event using "pandoc" that creates an rtf file out of RELEASE_NOTES.md
194* It is expected inside the folder "%LOCALAPPDATA%\Pandoc\pandoc.exe"
195* Setup can be downloaded at https://pandoc.org/installing.html