Skip to content

Commit 5481e14

Browse files
mkraposhinmkraposhin
authored
Dev contrib instr (#6)
* Contributor Instructions first revision * Contributor Instructions first revision * Format changes to Contributor Instructions first revision * Format changes to Contributor Instructions first revision * amendments to contributors instruction after first usage, links to chats were added * amendments to contributors instruction after first usage, links to chats were added * lists formattings * lists formattings * lists formattings * lists formattings * lists formattings * lists formattings * lists formattings * lists formattings * lists formattings
1 parent 02ed586 commit 5481e14

File tree

2 files changed

+187
-110
lines changed

2 files changed

+187
-110
lines changed

‎contributing-to-opensdn/getting-started/getting-started-with-opensdn-development.rst

Lines changed: 115 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,205 +1,210 @@
1-
Getting started as a developer
2-
==============================
1+
.. _Ref0: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
2+
3+
.. _Ref1: https://gerrit-review.googlesource.com/Documentation/user-notify.html
4+
5+
.. _Ref2: https://docs.opendev.org/opendev/git-review/latest/installation.html
6+
7+
.. _Ref3: https://github.com/OpenSDN-io/community/issues
8+
9+
.. _Ref4: https://github.com/orgs/OpenSDN-io/discussions
10+
11+
.. _Ref5: https://discord.gg/35533ukb
12+
13+
.. _Ref6: https://t.me/tungstenfabric_ru
14+
15+
Getting started as a contributor
16+
================================
317

418
This brief note would serve as a reference for a developer looking to
5-
start-up on the OpenSDN development environment.
19+
start-up on the contributing to OpenSDN platform.
620

7-
PLEASE NOTE: Until 2018, OpenSDN was named “OpenContrail”. There
8-
are still several references to the old name in the code and other
9-
utilities.
21+
PLEASE NOTE: Until 2023, OpenSDN was named “Tungsten Fabric” and
22+
before 2019 it had title “OpenContrail”. There are still several
23+
references to the old name in the code and other utilities.
1024

25+
1. Prerequisites
26+
----------------
1127

12-
1. OS installation and configuration
13-
------------------------------------
28+
Before contributing you will need next accounts:
1429

15-
Install Centos 7 for a stable installation of OpenSDN.
30+
1. a `GitHub <https://github.com>`_ account with publicly available e-mail
31+
(Settings -> Public profile -> Public e-mail);
1632

17-
You can also use Ubuntu 20.04 (In case of problems, check https://github.com/OpenSDN-io/tf-devstack)
33+
2. a `Gerrit <https://gerrit.opensdn.io>`_ account linked to the GitHub
34+
account (using the GitHub account credentials).
1835

19-
1.1 Relevant packages for the OpenSDN installation
20-
----------------------------------------------------------
36+
2. Git installation and configuration
37+
-------------------------------------
2138

22-
::
39+
2.1 Installation of the Git version control system
40+
---------------------------------------------------
41+
Next programs will be needed: git command and OpenSSH server.
42+
For example, on RPM based systems (CentOS, Fedora, etc) they can be
43+
installed with these commands:
44+
45+
::
2346

2447
sudo yum update
2548
sudo yum install git
2649
sudo yum install git-core
2750
sudo yum install openssh-server
2851

29-
1.2 Generate SSH key and add it to local SSH-agent
30-
--------------------------------------------------
52+
2.2 Generation of an SSH key
53+
----------------------------
54+
55+
If an SSH key was already generated, then this step can be omitted.
3156

3257
Ref:
3358
https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account
3459

35-
::
60+
::
3661

3762
ssh-keygen -t rsa -b 4096 -C "<username@someone.com>" //press "Enter" every time you see question
3863
eval $(ssh-agent -s)
3964
ssh-add ~/.ssh/id_rsa
40-
cat ~/.ssh/id_rsa.pub
4165

42-
Copy the entire output line(your public ssh id)
66+
Where "<username@someone.com>" corresponds to your GitHub email address.
4367

4468

45-
1.3 Add SSH key to GitHub account
69+
2.3 Add SSH key to GitHub account
4670
---------------------------------
4771

48-
1. Go to profile and select settings
49-
50-
2. Choose SSH and GPG keys -> New SSH key
72+
1. Run `GitHub <https://github.com>`_ web page in a browser.
5173

52-
3. Give a title for the key
74+
2. Go to profile and select settings.
5375

54-
4. Paste the key copied in step 1.2
76+
3. Choose SSH and GPG keys -> New SSH key.
5577

56-
5. Add SSH key
78+
4. Give a title for the key in "Title" field.
5779

58-
6. Make sure that in GitHub settings in Public profile you have public email(that you will add to global git config)
59-
This is required for the correct operation of the Gerrit
80+
5. Copy the public SSH key (for example, obtained from step 2.2):
6081

82+
::
6183

62-
2. OpenSDN + Devstack setup(Ansible Deployer)
63-
-----------------------------------------------------
64-
65-
Ref: https://github.com/OpenSDN-io/tf-devstack
66-
67-
If you have any questions, you can see more detailed instructions in this README:
68-
69-
https://github.com/OpenSDN-io/tf-devstack/tree/master/ansible
84+
cat ~/.ssh/id_rsa.pub
7085

71-
2.1 Create a nonroot user and add it to the wheel group
72-
-------------------------------------------------------
86+
6. Paste the public SSH key into "Key" field.
7387

74-
::
88+
7. Add SSH key.
7589

76-
sudo useradd <username>
77-
sudo passwd <username>
78-
sudo usermod -aG wheel <username>
90+
8. Make sure that in GitHub settings in Public profile you have public email
91+
(the one you will add to global git config). This is required for the correct
92+
operation of the Gerrit (see section 1.1).
7993

8094

81-
Modify user rigths configuration. Open the sudoers file
95+
3. Setting up Gerrit for committing code changes for a review
96+
-------------------------------------------------------------
8297

83-
::
98+
Reviewing process is organized using Gerrit system and
99+
"git review" command, Ref1_, Ref2_.
84100

85-
sudo visudo
101+
3.1 Setup SSH access
102+
--------------------
86103

87-
In the opened file, locate the line
104+
1. Log into your `OpenSDN Gerrit account <https://gerrit.opensdn.io>`_
105+
using via GitHub credentials.
88106

89-
::
107+
2. Go to top-right corner -> Settings.
90108

91-
%wheel ALL=(ALL) ALL
109+
3. Left panel: SSH Keys -> New SSH key.
92110

93-
Change it to
111+
4. Copy the public SSH key from step 2.3.5.
94112

95-
::
113+
5. Test the SSH access using your Gerrit account name "sshusername":
96114

97-
%wheel ALL=(ALL) NOPASSWD: ALL
115+
::
98116

99-
Switch to the new user and navigate to the home directory
117+
$ ssh -p 29418 sshusername@gerrit.opensdn.io
100118

101-
::
119+
6. After the execution, you should see:
102120

103-
su <username>
104-
cd
121+
::
105122

123+
**** Welcome to Gerrit Code Review ****
106124

107-
2.1 Clone Contrail-installer and devstack Repositories
108-
------------------------------------------------------
125+
Hi <sshusername>, you have successfully connected over SSH.
109126

110-
::
127+
Unfortunately, interactive shells are disabled.
128+
To clone a hosted Git repository, use:
111129

112-
git clone http://github.com/OpenSDN-io/tf-devstack
130+
git clone ssh://sshusername@gerrit.opensdn.io:29418/REPOSITORY_NAME.git
113131
132+
Connection to hostname closed.
114133

115-
2.2 Set up OpenSDN
116-
--------------------------
117-
118-
Execute script and wait for installation:
119-
::
120-
121-
./tf-devstack/ansible/run.sh //
122134

123-
2.3 Accessing Openstack and OpenSDN GUIs
124-
------------------------------------------------
125-
Openstack and contrail GUIs can be accessed as follows:-
135+
3.2 Pushing code changes for a review
136+
-------------------------------------
126137

127-
1. OpenSDN GUI: :code:`http://localhost:8143/`
138+
1. Install git-review utility. For example, on RPM-based systems run the
139+
command:
128140

129-
2. Openstack GUI: :code:`http://localhost/dashboard/` (only if you have installed with the openstack orchestrator)
141+
::
130142

143+
sudo yum install git-review
131144

132-
3. Setting up Gerrit for committing code-changes for review
133-
-----------------------------------------------------------
145+
Or it can be installed using pip Ref2_:
134146

135-
https://gerrit-review.googlesource.com/Documentation/user-notify.html
147+
::
136148

137-
3.1 Setup SSH access
138-
--------------------
149+
sudo pip install git-review
139150

140-
1. Log into your account at https://gerrit.opensdn.io (via GitHub)
141151

142-
2. Go to top-right corner -> settings
152+
2. Configure Gerrit:
143153

144-
3. Left panel: SSH Keys -> New SSH key
154+
::
145155

146-
4. Copy ssh key from step 1.2
156+
git config --global user.email username@someone.com
157+
158+
where "username@someone.com" is your email address that is publicly visible on
159+
your GitHub profile page.
147160

148-
5. Test the SSH access
161+
3. Clone the repo where your changes need to be introduced:
149162

150163
::
151164

152-
$ ssh -p 29418 sshusername@gerrit.opensdn.io
153-
154-
**** Welcome to Gerrit Code Review ****
165+
git clone ssh://sshusername@gerrit.opensdn.io:29418/opensdn-io/REPOSITORY_NAME
166+
167+
where "sshusername" is your OpenSDN Gerrit account name and "REPOSITORY_NAME"
168+
is the name of an OpenSDN repository (e.g., tf-dev-env, tf-controller, etc).
169+
Available OpenSDN repositories are listed `here <https://gerrit.opensdn.io/admin/repos>`_.
155170

156-
Hi <sshusername>, you have successfully connected over SSH.
171+
4. Introduce your changes to the source code of the cloned repository.
157172

158-
Unfortunately, interactive shells are disabled.
159-
To clone a hosted Git repository, use:
173+
5. Commit the changes
160174

161175
::
162176

163-
git clone ssh://sshusername@gerrit.opensdn.io:29418/REPOSITORY_NAME.git
164-
165-
Connection to hostname closed.
177+
git commit -m "<commit-note>" -s
166178

167-
3.2 Pushing code-changes for review
168-
-----------------------------------
179+
"-s" option is needed to sign a commit with your own e-mail and digital
180+
signature.
169181

170-
171-
1. Install git-review
182+
6. Push the locally committed changes up for review
172183

173184
::
174185

175-
sudo yum install git-review
186+
git review
176187

177-
2. Configure Gerrit
188+
In case of successfull execution of the command, you will see in your terminal:
178189

179190
::
180191

181-
git config --global user.email username@someone.com
182-
183-
3. Clone the repo where changes need to be committed
192+
remote: SUCCESS
184193

185-
::
194+
NOTE. If any of the steps above have raised questions you can:
186195

187-
git clone
188-
ssh://sshusername@gerrit.opensdn.io:29418/REPOSITORY_NAME.git
196+
* create an issue on in the community repository Ref3_;
189197

190-
4. Commit the changes
198+
* discuss your question in the discussions section Ref4_;
191199

192-
::
200+
* or ask for help in Discord Ref5_ or in Telegram Ref6_.
193201

194-
git commit -m "<commit-note>"
195202

196-
Note: please ensure that any change being committed should have a corresponding
197-
launch-pad bug-id mentioned in the commit message, i.e. "Bug #1679466"
203+
4. References
204+
-------------
198205

199-
5. Push the locally committed changes up for review
206+
1. Ref1_ : Gerrit Code Review - Email Notifications
200207

201-
::
208+
2. Ref2_ : gitreview. Installation and Configuration
202209

203-
git review
204210

205-
NOTE. If any of the steps above have raised questions, you can read the documentation at the link above

‎contributing-to-opensdn/getting-started/opensdn-plus-devstack-setup.rst

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
2. OpenSDN + Devstack setup(Ansible Deployer)
2+
-----------------------------------------------------
3+
4+
Install Centos 7 for a stable installation of OpenSDN.
5+
6+
You can also use Ubuntu 20.04 (In case of problems, check https://github.com/OpenSDN-io/tf-devstack)
7+
8+
Ref: https://github.com/OpenSDN-io/tf-devstack
9+
10+
If you have any questions, you can see more detailed instructions in this README:
11+
12+
https://github.com/OpenSDN-io/tf-devstack/tree/master/ansible
13+
14+
2.1 Create a nonroot user and add it to the wheel group
15+
-------------------------------------------------------
16+
17+
::
18+
19+
sudo useradd <username>
20+
sudo passwd <username>
21+
sudo usermod -aG wheel <username>
22+
23+
24+
Modify user rigths configuration. Open the sudoers file
25+
26+
::
27+
28+
sudo visudo
29+
30+
In the opened file, locate the line
31+
32+
::
33+
34+
%wheel ALL=(ALL) ALL
35+
36+
Change it to
37+
38+
::
39+
40+
%wheel ALL=(ALL) NOPASSWD: ALL
41+
42+
Switch to the new user and navigate to the home directory
43+
44+
::
45+
46+
su <username>
47+
cd
48+
49+
50+
2.1 Clone Contrail-installer and devstack Repositories
51+
------------------------------------------------------
52+
53+
::
54+
55+
git clone http://github.com/OpenSDN-io/tf-devstack
56+
57+
58+
2.2 Set up OpenSDN
59+
--------------------------
60+
61+
Execute script and wait for installation:
62+
::
63+
64+
./tf-devstack/ansible/run.sh //
65+
66+
2.3 Accessing Openstack and OpenSDN GUIs
67+
------------------------------------------------
68+
Openstack and contrail GUIs can be accessed as follows:-
69+
70+
1. OpenSDN GUI: :code:`http://localhost:8143/`
71+
72+
2. Openstack GUI: :code:`http://localhost/dashboard/` (only if you have installed with the openstack orchestrator)

0 commit comments

Comments
 (0)