1Contributing to Okta Open Source Repos
2======================================
3
4Sign the CLA
5------------
6
7If you haven't already, [sign the CLA](https://developer.okta.com/cla/).
8Common questions/answers are also listed on the CLA page.
9
10Summary
11-------
12
13This document covers how to contribute to an Okta Open Source project. These
14instructions assume you have a GitHub .com account, so if you don't have one
15you will have to create one. Your proposed code changes will be published to
16your own fork of the Okta Golang SDK project and you will submit a Pull Request
17for your changes to be added.
18
19_Lets get started!!!_
20
21
22Fork the code
23-------------
24
25In your browser, navigate to:
26[https://github.com/okta/okta-sdk-golang](https://github.com/okta/okta-sdk-golang)
27
28Fork the repository by clicking on the 'Fork' button on the top right hand
29side. The fork will happen and you will be taken to your own fork of the
30repository. Copy the Git repository URL by clicking on the clipboard next to
31the URL on the right hand side of the page under '**HTTPS** clone URL'. You
32will paste this URL when doing the following `git clone` command.
33
34On your computer, follow these steps to setup a local repository for working on
35the Okta Golang SDK:
36
37``` bash
38$ git clone https://github.com/YOUR_ACCOUNT/okta-sdk-golang.git
39$ cd okta-sdk-golang
40$ git remote add upstream https://github.com/okta/okta-sdk-golang.git
41$ git checkout master
42$ git fetch upstream
43$ git rebase upstream/master
44```
45
46Making changes
47--------------
48
49It is important that you create a new branch to make changes on and that you do
50not change the `master` branch (other than to rebase in changes from
51 `upstream/master`). In this example I will assume you will be making your
52changes to a branch called `feature_x`. This `feature_x` branch will be
53created on your local repository and will be pushed to your forked repository
54on GitHub. Once this branch is on your fork you will create a Pull Request for
55the changes to be added to the Okta Golang SDK project.
56
57It is best practice to create a new branch each time you want to contribute to
58the project and only track the changes for that pull request in this branch.
59
60``` bash
61$ git checkout master
62$ git checkout -b feature_x
63 (make your changes)
64$ git status
65$ git add <files>
66$ git commit -m "descriptive commit message for your changes"
67```
68
69> The `-b` specifies that you want to create a new branch called `feature_x`.
70> You only specify `-b` the first time you checkout because you are creating a
71> new branch. Once the `feature_x` branch exists, you can later switch to it
72> with only `git checkout feature_x`.
73
74
75Rebase `feature_x` to include updates from `upstream/master`
76------------------------------------------------------------
77
78It is important that you maintain an up-to-date `master` branch in your local
79repository. This is done by rebasing in the code changes from
80`upstream/master` (the official Okta Golang SDK project repository) into your
81local repository. You will want to do this before you start working on a
82feature as well as right before you submit your changes as a pull request. I
83recommend you do this process periodically while you work to make sure you are
84working off the most recent project code.
85
86This process will do the following:
87
881. Checkout your local `master` branch
892. Synchronize your local `master` branch with the `upstream/master` so you
90 have all the latest changes from the project
913. Rebase the latest project code into your `feature_x` branch so it is
92 up-to-date with the upstream code
93
94``` bash
95$ git checkout master
96$ git fetch upstream
97$ git rebase upstream/master
98$ git checkout feature_x
99$ git rebase master
100```
101
102> Now your `feature_x` branch is up-to-date with all the code in `upstream/master`.
103
104
105Make a GitHub Pull Request to contribute your changes
106-----------------------------------------------------
107
108When you are happy with your changes and you are ready to contribute them, you
109will create a Pull Request on GitHub to do so. This is done by pushing your
110local changes to your forked repository (default remote name is `origin`) and
111then initiating a pull request on GitHub.
112
113> **IMPORTANT:** Make sure you have rebased your `feature_x` branch to include
114> the latest code from `upstream/master`
115_before_ you do this.
116
117``` bash
118$ git push origin master
119$ git push origin feature_x
120```
121
122Now that the `feature_x` branch has been pushed to your GitHub repository, you
123can initiate the pull request.
124
125To initiate the pull request, do the following:
126
1271. In your browser, navigate to your forked repository:
128 [https://github.com/YOUR_ACCOUNT/okta-sdk-golang](https://github.com/YOUR_ACCOUNT/okta-sdk-golang)
1292. Click the new button called '**Compare & pull request**' that showed up just
130 above the main area in your forked repository
1313. Validate the pull request will be into the upstream `master` and will be
132 from your `feature_x` branch
1334. Enter a detailed description of the work you have done and then click
134 '**Send pull request**'
135
136If you are requested to make modifications to your proposed changes, make the
137changes locally on your `feature_x` branch, re-push the `feature_x` branch to
138your fork. The existing pull request should automatically pick up the change
139and update accordingly.
140
141Cleaning up after a successful pull request
142-------------------------------------------
143
144Once the `feature_x` branch has been committed into the `upstream/master`
145branch, your local `feature_x` branch and the `origin/feature_x` branch are no
146longer needed. If you want to make additional changes, restart the process
147with a new branch.
148
149> **IMPORTANT:** Make sure that your changes are in `upstream/master` before
150> you delete your `feature_x` and
151`origin/feature_x` branches!
152
153You can delete these deprecated branches with the following:
154
155``` bash
156$ git checkout master
157$ git branch -D feature_x
158$ git push origin :feature_x
159```
View as plain text