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
* Add the Thanks page in.
* Split out the developer guides for documentation and appliction to make them more distinct.
* Simplify some of the Git info.
* Add more cross links to appropriate sections.
description: How to contribute to the Vixen project.
9
9
cascade:
10
10
- type: docs
11
11
---
12
12
13
-
Vixen is an open source project and we love getting patches and contributions to make Vixen and its docs even better.
14
-
15
-
## Contributing to Vixen
16
-
17
-
The Vixen code itself lives in <https://github.com/vixenlights/vixen>.
13
+
Vixen is an open source project and we love getting patches and contributions to make Vixen and its docs even better. Even people who are willing to test and provide feedback are a welcome benefit to the project.
18
14
19
15
### Contributor License Agreement
20
16
21
17
Contributions to this project become part of the project and are subject to the open source licensing.
22
18
23
-
### Code reviews
24
-
25
-
All submissions, including submissions by project members, require review. We
26
-
use GitHub pull requests for this purpose. Consult
27
-
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
28
-
information on using pull requests.
29
-
30
-
### Community guidelines
31
-
32
-
This project follows
33
-
[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
34
-
35
-
### Creating issues
36
-
37
-
Alternatively, if there's something you'd like to see in Vixen (or if you've found something that isn't working the way you'd expect), but you're not sure how to fix it yourself, please create an [issue](https://bugs.vixenlights.com).
38
-
39
-
## Contributing to these docs
40
-
41
-
This user guide is a Docsy site that uses the Hugo static site generator. We welcome updates to the docs!
42
-
43
-
### Updating a single page
44
-
45
-
If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you:
46
-
47
-
1. Click **Edit this page** in the top right hand corner of the page.
48
-
1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
49
-
50
-
### Previewing your changes locally
51
-
52
-
If you want to run your own local Hugo server to preview your changes as you work:
53
-
54
-
1. Follow the instructions in [Getting started](/docs/getting-started) to install Hugo and any other tools you need.
55
-
1. Fork the [Vixen Website](https://github.com/vixenlights/web.vixenlights.com) repo into your own project, then create a local copy using `git clone`:
1. Change to the `web.vixenlights.com` directory and run the following Hugo command to build the site and start the Hugo server.
62
-
63
-
```sh
64
-
cd web.vixenlights.com
65
-
hugo server
66
-
```
19
+
### Code Reviews
67
20
68
-
By default your site will be available at http://localhost:1313/. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
21
+
All submissions, including submissions by project members, require review. We use GitHub pull requests and review process for this purpose. Consult [GitHub Help][1] for more information on using pull requests.
69
22
70
-
2. Continue with the usual GitHub workflow to edit files, commit them, push the
71
-
changes up to your fork, and create a pull request.
23
+
### Community Guidelines
72
24
73
-
### Creating an issue
25
+
This project follows [Google's Open Source Community Guidelines][2].
74
26
75
-
If there's something you'd like to see in the docs, but you're not sure how to fix it yourself, please create an issue in [this repository](https://github.com/vixenlights/we/vixenlights.com). You can also create an issue about a specific page by clicking the **Create Documentation Issue** link in the top right hand corner of the page.
description: How to contribute to the Vixen documentation.
6
+
---
7
+
8
+
### Overview
9
+
10
+
Vixen is an open source project and we love getting patches and contributions to make Vixen and its docs even better.
11
+
12
+
This user guide is a Docsy themed site that uses the Hugo static site generator. The code for the website is hosted on [Github][5].
13
+
14
+
We welcome updates to the docs!
15
+
16
+
### Updating a single page
17
+
18
+
If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you:
19
+
20
+
1. Click **Edit this page** in the top right hand corner of the page.
21
+
2. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
22
+
3. Submit a pull request to the develop branch in the repository and it will be reviewed for inclusion.
23
+
24
+
### Previewing your changes locally
25
+
26
+
If you want to run your own local Hugo server to preview your changes as you work:
27
+
28
+
1. Follow the instructions in [Docsy Getting Started][6] to install Hugo and any other tools you need.
29
+
2. Fork the [Vixen Website][5] repo into your own project, then create a local copy using `git clone`:
3. Change to the `web.vixenlights.com` directory and run the following Hugo command to build the site and start the Hugo server.
36
+
37
+
```sh
38
+
cd web.vixenlights.com
39
+
npm install
40
+
hugo server
41
+
```
42
+
43
+
By default your site will be available at http://localhost:1313/. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
44
+
45
+
4. Continue with the usual GitHub workflow to edit files, commit them, push the
46
+
changes up to your fork, and create a pull request.
47
+
48
+
### Creating an issue
49
+
50
+
If there's something you'd like to see in the docs, but you're not sure how to fix it yourself, please create an [Issue][7] on Github forthis repository. You can also create an issue about a specific page by clicking the **Create Documentation Issue** linkin the top right hand corner of the page.
description: How to contribute to the Vixen application.
6
+
---
7
+
8
+
### Overview
9
+
10
+
Vixen is an open source project and we love getting patches and contributions to make Vixen and its docs even better.
11
+
12
+
The Vixen application code is hosted on [Github][1]. You can clone the repository to get a copy of the source code to work with.
13
+
14
+
### Development Libraries
15
+
16
+
There are a few libraries and tools that you need to have installed in order to get the application to build. Depending on how much you develop in other projects you may have these already installed.
17
+
18
+
* Windows 10 or higher.
19
+
* Visual Studio 2022
20
+
* Git
21
+
* Microsoft .NET Framework 4.8
22
+
* Microsoft Visual C++ 2019 x86 Redistributable
23
+
* Microsoft Visual C++ 2019 x64 Redistributable
24
+
25
+
The current build target is .NET 4.8 and Visual C++ 2019, but we are actively migrating to .NET 6 and will be using Visual C++ 2022.
26
+
27
+
See this [article][4] on Visual Studio settings you should use.
28
+
29
+
See this [article][5] for information on Git.
30
+
31
+
### Workflow
32
+
33
+
When contributing to Vixen, we like to track all issues and improvements in our [JIRA bug tracker][2]. Work should have an associated issue created for it. It is a good idea to have an account in JIRA so you can work with the issues. See [Lifecycle][7] of an issue for guidance on how we manage issues.
34
+
35
+
You should strive to name your branches with the ticket number. i.e. VIX-2345. Any commits to the branch should start with the ticket number as well and then follow Git guidlines for commit messages. All submissions are done through pull requests on Github. See [Branching Practices][6] for guidance on this topic.
36
+
37
+
More information on how we manage JIRA can be found [here][3].
38
+
39
+
### Creating Issues
40
+
41
+
Alternatively, if there's something you'd like to see in Vixen (or if you've found something that isn't working the way you'd expect), but you're not sure how to fix it yourself, please create an [Issue][2] in our JIRA board for anything in the application.
Copy file name to clipboardExpand all lines: content/en/developer/git-information.md
+14-14Lines changed: 14 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,17 @@
1
1
---
2
2
title: Git Information
3
3
author: Vixen Team
4
-
weight: 10
4
+
weight: 30
5
+
description: This section covers the source code tooling.
5
6
---
6
7
7
-
### Tools
8
+
### Overview
9
+
10
+
The Vixen project uses [Git][2] for our source code management. [Github][1] is our collaboration tool.
8
11
9
-
The Vixen project uses Git for our source code management. Github is our collaboration tool.
12
+
### Tools
10
13
11
-
There are many tools to work with a Git based project. Yo uwill at minimum need the Git libraries installed.
14
+
There are many tools to work with a Git based project. You will at minimum need the Git libraries installed.
12
15
13
16
[Git SCM][2]
14
17
@@ -18,26 +21,23 @@ TortoiseGit is a UI tool that can make it easier for some to use Git. This allow
18
21
19
22
[TortoiseGit Manuals][4]
20
23
21
-
Visual studio also has support within it for Git and there are also many other plugins that provide integrations as well. You are welcome to use whatever you like and are comfortable with.
24
+
Visual Studio also has support within it for Git and there are also many other plugins that provide integrations as well. You are welcome to use whatever you like and are comfortable with.
22
25
23
26
### Branching Practices
24
27
25
28
The general idea is that the master branch is, tracking the development for the next version. It's stuff that's going into the product, and will be included in the next version unless something is found to have an issue in testing.
26
29
27
-
(a) You should not commit stuff to your master branch. You should keep it up to date with the real master and make branches off of it for any new work your do. When you first decide to do work on Vixen, you would fork the master at [Vixen Source][5] to your own copy of it. You should be able to build and get a running version of Vixen from that is current. Then you can easily make branches from that to work on. Tools like TortoiseGit make it easier to manage changing branches and committing work.
28
-
29
-
As a maintainer, even I do not commit any work directly to the master branch. All commits on the master branch are actually merges of work from other branches.
30
-
31
-
(b) All work should be done based off of a ticket in the [JIRA Bug Tracker][6]. When you take on work for a particular item, you should create a branch off of the current master and name it the same as the ticket you are working on. I.E. VIX-1024. This provides a clear reference back to the description of the problem or feature. In addition to this, each commit should start with the ticket number as well. This will allow those commits to be linked to the ticket when they are eventually merged into the master. You should ensure you have an open ticket to begin work so that this tracking can occur. Once the ticket it open and assigend to you, you can move it to start work. This will indicate to other developers you are working on the ticket. Once you complete the work, you can submit a pull request to the Vixen repository where it can be reviewed. The JIRA ticket will reflect that a PR has been submitted. Once reviewed and approved, the ticket will transition states based on it being merged, built and closed automatically. You will not need to transition JIRA beyond the initial start work in normal circumstances. JIRA will track the changes when they are committed to the main repository. The build that corresponds to the change will be marked in the JIRA ticket along with links to the commits involved.
30
+
* You should not commit code to your master branch. You should keep it up to date with the real master and make branches off of it for any new work you do. When you first decide to do work on Vixen, you should fork the master at [Github][5] to your own copy of it. You should be able to build and get a running version of Vixen from that is current. Then you can easily make branches from that to work on.
32
31
33
-
(c) If the item you are working on will span some time and the current master gets updated with new features from other developers, you can keep your branch in sync by rebasing your changes onto the current version of the master. You would sync your copy of the master from the master branch tree first. Then you can rebase your branch onto that. This will replay your commits onto the tail of the master giving you a up to date branch. Try to avoid merging the changes in the master into your own branch as this creates a messy commit history. More information on how to rebase can be found [here][7].
32
+
* All work should be done based off of a ticket in the [Bug Tracker][6]. When you take on work for a particular item, you should create a branch off of the current master and name it the same as the ticket you are working on. I.E. VIX-1024. This provides a clear reference back to the description of the problem or feature. In addition to this, each commit should start with the ticket number. This will allow those commits to be linked to the ticket when they are eventually merged into the master. You should ensure you have an open ticket to begin work so that this tracking can occur. Once the ticket it open and assigend to you, you can move it to start work. This will indicate to other developers you are working on the ticket. Once you complete the work, you can submit a pull request to the Vixen repository where it can be reviewed. The JIRA ticket will reflect that a pull request has been submitted. Once reviewed and approved, the ticket will transition states based on it being merged, built and closed automatically. You will not need to transition JIRA beyond the initial start work in normal circumstances. The build that corresponds to the change will be marked in the JIRA ticket along with links to the commits involved. The maintainer will close the ticket when it is merged.
34
33
35
-
(d) If you are collaborating with another developer, then you may want to share work on a branch. Here you can both work on the same branch shared publicly or you can merge changes between yourself. This is not very common in our development structure so ask questions if it comes up and we can help guide you through it.
34
+
*If the item you are working on will span some time and the current master gets updated with new features from other developers, you can keep your branch in sync by rebasing your changes onto the current version of the master. You would do a git pull to your master from the master branch tree first. Then you can rebase your branch onto that. This will replay your commits onto the tail of the master giving you a up to date branch. Try to avoid merging the changes in the master into your own branch as this creates a messy commit history. More information on how to rebase can be found [here][7].
36
35
37
-
(e) If you want to have a play with someone else's branch (to test, or add features to it), as long as they have pushed a copy of it out to their public repository, then you can always make your own branch at that point, and go from there. For example, Jeff might take a look at Jon's _VersionControl_branch, and make a new one for himself, called _copy-branch_ or something. He can do some more work to do with the version control, maybe updating stuff, adding a new feature, etc. Then, if Jon likes it, he can merge from Jeff's VC branch back into his own VC branch. (since it's all separate to 'master', he can do what he likes with it.) Once all the work is done between the two developers, the version with all the changes compiled together can be merged into the master.
36
+
* If you are collaborating with another developer, then you may want to share work on a branch. Here you can both work on the same branch shared publicly or you can merge changes between yourself. This is not very common in our development structure, so ask questions if it comes up and we can help guide you through it.
38
37
39
-
(f) When work is complete on a branch, That branch should be pushed to your public repository and a pull request against the Vixen master created to indicate it is ready to be reviewed and merged.
38
+
* Larger bodies of work will be conducted on a feature branch in the repository. Here something like an Epic can we worked on by multiple developers, or broken up into multiple parts and that can be assembled on the feature branch and then a singular pull request can merge the entirety of that back to master.
0 commit comments