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