docs/testing/developer/design/02-Get_started_Guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation and others.
   4
   5 .. OPNFV SAMPLEVNF Documentation design file.
   6
   7 ====================================
   8 Get started as a SampleVNF developer
   9 ===================================
  10
  11 .. _SampleVNF: https://wiki.opnfv.org/samplevnf
  12 .. _Gerrit: https://www.gerritcodereview.com/
  13 .. _JIRA: https://jira.opnfv.org
  14 .. _Technical_Briefs: https://wiki.opnfv.org/display/SAM/Technical+Briefs+of+VNFs
  15
  16 Prerequisite knowledge
  17 ======================
  18
  19 Development/Contribution to SampleVNF requires knowledge of networking
  20 technologies including knowledge of network protocols and hands-on experience
  21 with relevant open-source software, such as Linux*, SDN, NFVI and the DPDK (if
  22 VNF is based on DPDK libraries).
  23 Developer needs debugging and benchmarking skills, as well as understanding of
  24 NFVi infrastructure across multiple domains.
  25
  26 There are many ways to contribute to samplevnf.
  27
  28  * Develop new test cases in samplevnf
  29  * Review code changes
  30  * Develop/contribute to existing VNFs or new VNFs
  31  * Write samplevnf documentation
  32
  33 Technical Briefs of exists in VNFs in Technical_Briefs_
  34
  35
  36 Get Started
  37 ===========
  38
  39 Where can I find some help to start?
  40
  41 You can also directly contact us by mail with [SampleVNF] prefix in the title
  42 at opnfv-tech-discuss@lists.opnfv.org or on the IRC chan #opnfv-samplevnf.
  43
  44 How TOs
  45 -------
  46
  47 How can I contribute to SampleVNF?
  48
  49 If you are already a contributor of any OPNFV project, you can contribute to
  50 samplevnf.
  51 If you are totally new to OPNFV, you must first create your Linux Foundation
  52 account, then contact us in order to declare you in the repository database.
  53
  54 We distinguish 2 levels of contributors:
  55 The standard contributor can push patch and vote +1/0/-1 on any samplevnf patch
  56 The committer can vote -2/-1/0/+1/+2 and merge.
  57 SampleVNF committers are promoted by the samplevnf contributors.
  58
  59 Gerrit & JIRA
  60 -------------
  61
  62 OPNFV uses Gerrit_ for web based code review and repository management for the
  63 Git Version Control System. You can access OPNFV Gerrit from this link.
  64 Please note that you need to have Linux Foundation ID in order to use OPNFV
  65 Gerrit.
  66 You can get one from this link.
  67
  68 OPNFV uses JIRA_ for issue management. An important principle of change
  69 management is to have two-way traceability between issue management (i.e. JIRA_)and the code repository (via Gerrit).
  70 In this way, individual commits can be traced to JIRA issues and we also know
  71 which commits were used to resolve a JIRA issue.
  72 If you want to contribute to samplevnf, you can pick a issue from SampleVNF's
  73 JIRA dashboard or you can create you own issue and submit it to JIRA.
  74
  75 Submitting code to Gerrit
  76 -------------------------
  77
  78 Installing and configuring Git and Git-Review is necessary in order to submit
  79 code to Gerrit.
  80 The Getting to the code page will provide you with some help for that.
  81
  82 Comitting the code with Git
  83 Open a terminal window and set the project's directory to the working directory
  84 using the cd command.
  85 In this case "/home/opnfv/samplevnf" is the path to samplevnf project folder.
  86 Replace this with the path of your own project.
  87
  88 ::
  89
  90   cd /home/opnfv/samplevnf
  91
  92 Tell Git which files you would like to take into account for the next commit.
  93 This is called 'staging' the files, by placing them into the staging area,
  94 using the 'git add' command (or the synonym 'git stage' command).
  95
  96 ::
  97
  98   git add samplevnf/samples/sample.yaml
  99   ...
 100
 101 Alternatively, you can choose to stage all files that have been modified
 102 (that is the files you have worked on) since the last time you generated a
 103 commit, by using the -a argument.
 104
 105 ::
 106
 107   git add -a
 108
 109 Git won't let you push (upload) any code to Gerrit if you haven't pulled
 110 the latest changes first.
 111 So the next step is to pull (download) the latest changes made to the project
 112 by other collaborators using the 'pull' command.
 113
 114 ::
 115
 116   git pull
 117
 118
 119 Now that you have the latest version of the project and you have staged the
 120 files you wish to push, it is time to actually commit your work to your local
 121 Git repository.
 122
 123 ::
 124
 125   git commit --signoff -m "Title of change
 126
 127   Test of change that describes in high level what
 128   was done. There is a lot of documentation in code
 129   so you do not need to repeat it here.
 130
 131   JIRA: SAMPLEVNF-XXX"
 132
 133 The message that is required for the commit should follow a specific set of
 134 rules. This practice allows to standardize the description messages attached
 135 to the commits, and eventually navigate among the latter more easily.
 136
 137 Verify your patch locally before submitting
 138 Once you finish a patch, you can submit it to Gerrit for code review.
 139 A developer sends a new patch to Gerrit will trigger patch verify job on
 140 Jenkins CI.
 141
 142 Pushing the code to Gerrit for review
 143 Now that the code has been comitted into your local Git repository the
 144 following step is to push it online to Gerrit for it to be reviewed. The
 145 command we will use is 'git review'.
 146
 147 ::
 148
 149   git review
 150
 151 This will automatically push your local commit into Gerrit.
 152
 153 Code review
 154 You can add Samplevnf committers and contributors to review your codes.
 155
 156 Modifying the code under review in Gerrit
 157 At the same time the code is being reviewed in Gerrit, you may need to edit it to
 158 make some changes and then send it back for review. The following steps go
 159 through the procedure.
 160 Once you have modified/edited your code files under your IDE, you will have to
 161 stage them.
 162 The 'status' command is very helpful at this point as it provides an overview
 163 of Git's current state.
 164
 165 ::
 166
 167   git status
 168
 169 The output of the command provides us with the files that have been modified
 170 after the latest commit.
 171
 172 You can now stage the files that have been modified as part of the Gerrit code
 173 review edition/modification/improvement using git add command.
 174 It is now time to commit the newly modified files, but the objective here is
 175 not to create a new commit, we simply want to inject the new changes into the
 176 previous commit.
 177
 178 You can achieve that with the '--amend' option on the 'commit' command:
 179
 180 ::
 181
 182   git commit --amend
 183
 184 If the commit was successful, the 'status' command should not return the updated
 185 files as about to be commited.
 186
 187 The final step consists in pushing the newly modified commit to Gerrit.
 188
 189 ::
 190
 191   git review
 192
 193 References
 194 [1]: http://artifacts.opnfv.org/samplevnf/docs/testing_user_userguide_vACL/index.html