Skip to content

developing

Jump to bottom Edit New page
Rodrigo Avancini edited this page Mar 12, 2019 · 92 revisions

Developing TerraME

Pedro R. Andrade, Rodrigo Avancini

Summary

GitHub

Before starting, we strongly recommend you to see videos about GitHub and Pull Requests and practice a little bit with one of the available projects in githubschool. The idea is to work with forks in your own GitHub account and create pull requests that will be accepted by the project manager.

In order to work with Github, we recommend to use a client that helps a lot the development. We recomment two:

  • SourceTree: A free client for Mac and Windows. After some time it asks you to register but it is still free.
  • Smartgit: A non-free client for all operational systems. Although not free, we used it sucessfully without registering.

The process to develop TerraME requires each developer to create his or her own fork. In TerraME/terrame, click in Fork and create one into your own profile. Download this fork using SourceTree in your machine.

Folder structure

TerraME has the following directory structure:

  • base: The basic package, implementing all Lua types (Agent, Cell, CellularSpace, and so one). See how this directory is organized in the documentation of Packages.
  • build: Folder with scripts to compile TerraME.
  • dependencies: Source code of some dependencies.
  • installer: Scripts to build installers.
  • licenses: A set of license files for TerraME and the libraries it uses.
  • luadoc: A package used by execution option -doc.
  • res: A package with the application icon.
  • src: The internal source code of TerraME.
  • test: Folder with packages and scripts for execution tests.

The root directory also has a file called .gitignore. It contains a list of files and directories that will be ignored by git.

Issues

Every issue must be written in English. As TerraME uses American english, it is recommended to use its grammar. Each issue must belong to one of the four labels below:

  1. Enhancement: Something that increases the functionalities of TerraME, such as a new type, function, or parameter.
  2. Bug: An error that must be removed. Usually errors are related to the source code, but they are not limited to. We can have bugs related to data, tests, as well as documentation.
  3. Task: Something that needs to be done but will not create a new functionality or remove an error. For example, adding a new example or database, adding new tests, improving an algorithm, compiling a new library, building an installer, or updating the documentation.
  4. Question: An idea that might become a new requisite for the system. Questions cannot belong to the next version to be released: they must belong to a future version.

Each issue must be associated to one or more development labels:

  1. C++: It involves C++ and/or compilation.
  2. Lua: It involves files in base/lua or src/lua.
  3. Test: It involves files in base/tests or test.
  4. Data: It involves files in base/data and/or base/data.lua.
  5. Documentation: It involves files in ludoc, wiki issues, as well as documentation tags in base/lua, including @usage.

Finally, every issue might have a priority:

  1. High priority: This issues must be solved before others that does not have high priority.
  2. BLOCKING: The developer cannot solve any issue but this one.

Non-task and non-question issues that will not be closed by a commit must have one of the following labels:

  1. Invalid: A wrong issue that should not have been created.
  2. Duplicate: There is another issue with the same objective.
  3. Wontfix: Something that is not an error anymore.

Testing

Once you have implemented something that worth to be verified, you will need to execute tests to make sure your changes work and it does not have some side effect. The protocol to test TerraME includes three steps:

  1. Unit tests,
  2. Documentation,
  3. Execution tests,
  4. Repository tests (possibly), and
  5. Visual tests.

They are described as follows.

Unit tests

For basic information about test files, the verifications made in each test, and configuration files, see the document Building TerraME Packages.

Unit tests execute all the functions of TerraME and check if all source code lines were executed at least once (in fact, it does not check all lines because there are some source code lines that are ignored by the interpreted and so they need to be ignored by this check also). These tests are stored in base/tests. It contains four directories:

  1. core: Basic tests to all functions that do not use database nor graphical interface.
  2. database: Tests that need to access external files or databases. For instance, tests that read CSV files need to be stored in this directory.
  3. internal: Contains tests related to directory src/lua, that do not belong to base package and cannot have source code lines verified.
  4. observer: Stores all tests that use observers.

Each of them have two internal directories, basic, with tests that run correctlu, and alternative, with tests that produce errors.

Before running Unit tests, you will need to create two files in your current directory. The first file must be called config.lua, with information about database connection (user, host, and so on). An example of a file is shown below:

password = ""
drop = true
dbType = "mysql"

With this file, you can import the databases of base package, filling all the databases necessary to run all tests:

terrame -import

The second file to be created indicates that the test will check if all source code lines were executed at least one. You can choose the name for this file, and use it in the command to run the tests. For example, a given file t.lua contains:

lines = true

Then run the tests:

terrame -color -test t.lua

If everything runs fine there will be no red line in the final report. It will be something like:

Unit test report:
Tests were executed in 797.51 seconds.
Snapshots were saved in '.terrametmp_KBh7R'.
No print() calls were found when loading the package.
No variable is overwritten when loading the package.
There are no invalid files or directories in directory 'tests'.
All asserts were executed at least once.
All 494972 asserts were executed successfully.
All 492 tested functions do not have any unexpected execution error.
All 492 tested functions have at least one assert.
All 492 tested functions exist in the source code of the package.
No tested function creates or updates any global variable.
No function prints any text on the screen.
No assertError() calls have error messages pointing to internal files.
All 308 functions of the package were tested.
All lines from the source code were executed.
No new snapshot file was created.
All snapshot files were used in the tests.
All 22 examples were successfully executed.
No new log file was created.
Summing up, all tests were successfully executed.

During the implementation of an issue, if some function was added or removed, you will need to change tests/core/basics/Package.lua, in getPackage(), which counts the number of functions in base package. If some data file was added or removed, you will need to change the following functions, that count the number of files in the data directory:

  • tests/core/basics/Utils.lua, in function forEachFile(),
  • tests/core/basics/FileSystem.lua, in functions dir() and runCommand(), and
  • tests/core/basics/Package.lua, in function filesByExtension() (only if it is a csv file).

Documentation

For basic information about how to document each function and the verifications made, see the tutorial Building TerraME Packages.

Build the documentation again is also a way to test TerraME. It will check if all the functions and parameters are correctly documented, as well as run all the examples.

terrame -color -doc

If everything runs fine there will be no red line in the final report. The output will be something like:

Dcumentation report:
Documentation was built in 9.65 seconds.
35 HTML files were created.
All files are documented.
All fields of 'description.lua' are correct.
No problems were found in the documentation of data.
No problems were found in the documentation of fonts.
All source code lines starting with --- are valid.
There are no Models in the package.
All 292 global functions of the package are documented.
All functions of each file are declared only once.
All descriptions end with a correct character.
There is no duplicated tag in the documentation.
All tags with compulsory arguments were correctly used.
All 316 non-named arguments are documented.
No undefined arguments were found.
All available arguments of functions are used in their HTML tables.
All arguments used in the HTML tables are documented.
All non-deprecated functions have @usage.
All 292 functions call themselves in their @usage.
All 292 functions do not have any error in their @usage.
All @tabular are correctly described.
No invalid tags were found in the documentation.
All images are correctly used.
All 305 links were correctly built.
All 22 examples are correctly documented.
Summing up, all the documentation was successfully built.

Execution tests

Execution tests ensure that individual runs of TerraME work properly. It basically verifies if the files in src/lua are correctly implemented, testing TerraME with options like -doc, -test, -build, traceback in scripts with error, and so one. To do so, it executes TerraME with different arguments and redirect the output to a temporary file that needs to be compared with a log file.

Execution tests are stored in directory test. This directory contains the following files and directories:

  • commands.lua: Script that describe all tests to be executed. See below.
  • config: A set of config files to be used in tests for -test.
  • config.lua: A file with information to connect to a database. You should edit it with your own information.
  • log: Folder with all log files created by the tests.
  • packages: Folder with a set of packages to be tested. The objective of each package is described in its description.lua.
  • remove.lua: A Lua file that describes the files that need to be removed before executing the tests.
  • run.lua: A script to run all execution tests.
  • scripts: A directory with a set of scripts to be executed.

File commands.lua contains a set of tables. Each table has another set of tables that describe individual tests. These internal tables might contain a set of parameters:

  • arg: Additional arguments to the command line.
  • config: File in directory config that will be used in the tests.
  • package: Name of the package in directory packages that will be used. Each test that uses packages is executed twice. First with the package installed (terrame/bin/packages/...), and then as package stored in the current directory. Both tests will share the same log file.
  • quantity: Number of observers that will be created in the execution of a script.
  • script: Refers to a file in the directory scripts.

commands.lua can also have a boolean variable called show. If it is true, then all command lines are shown when executing the tests.

When executing individual tests, the outputs are matched with log files, according to the name of the table. For example, table

mode = {
    normal = {script = "basic.lua"},
    debug  = {script = "basic.lua", arg = "-mode=debug"},
    strict = {script = "basic.lua", arg = "-mode=strict"},
    quiet  = {script = "basic.lua", arg = "-mode=quiet"},
}

will use four log files: log/mode-normal.log, log/mode-debug.log, log/mode-strict.log, and log/mode-quiet.log. If some of these log files do not exist, the script will create it in the log directory and ask you to run the execution tests again. When comparing the outputs with log files, some lines can be ignored according to their content. These lines are described in function approximateLine() in run.lua, where it allows an error of a given amount of characters according to some patterns. For example, lines that contain seconds might have five different characters. If some significant change was made in the source code of TerraME, such as adding new functions, some updates on the reports, or new verifications, some of the log files should be removed in order to be updated. Then, it is possible to use your favorite Github client to see the changes in each log file. Note that the lines that should be ignored will be shown as different. Just discard the lines that should be ignored before commiting the changes. To run execution tests, use the following command:

terrame -color run.lua

If everything runs fine there will be no red line in the final report. The output will be something like:

Execution test report:
Tests were executed in 244 seconds.
Results were saved in '.terramerun_ps11y'.
All 104 commands were successfully executed.
All 6 builds for installed packages were successfully executed.
All 6 builds for local packages were successfully executed.
All logs for installed packages are correct.
All logs for local packages are correct.
No log file was created.
All observers are saved correctly.
All files and packages are used at least once in the tests.
Summing up, all tests were successfully executed.

Repository tests

Repository tests make sure that all the official packages work properly. It downloads, installs, and tests all those packages. Note that this kind of test should be executed only when the implemented changes guarantee backward compatibility.

Repository tests are stored in directory repository. This directory contains the following files and directories:

  • log: Folder with all log files created by repository tests.
  • test.lua: A script to run all repository tests.
  • packageList.lua: A script to create a summary of all available packages to be downloaded by TerraME when searching for new packages.

To run repository tests, use the following command:

terrame -color repository.lua

This test executes the following steps:

  1. Copy the already installed packages to a separate directory;
  2. Download, install, and verify the packages (-test and -doc);
  3. Rolls back the original installed packages.

Repository tests have the same strategy of log files from execution tests. If some verification does not match the log files then an error will be shown. If everything runs fine there will be no red line in the final report. The output will be something like:

Repository test report:
Tests were executed in 794 seconds.
The repository has 4 packages.
Results were saved in '.terramerepository_HoJkO'.
No repos log file was created.
All verifications were successfully executed.
Summing up, all tests were successfully executed.

Visual tests

Visual tests are the last step to guarantee that a release is correct. These tests need to be executed manually with the graphical interface to handle packages. Execute the following tests:

Test procedure Expected results
Install TerraME. TerraME should be successfully installed.
Open terminal or prompt. Set TerraME on Path: In Windows: #> set PATH=%PATH%;%TME_PATH%, in Mac: #> export PATH=$PATH:/Application/terrame.app/Contents/bin, in Linux: #> export TME_PATH=...place/to/terrame/bin & export PATH=$PATH:$TME_PATH & export LD_LIBRARY_PATH=$TME_PATH. Enter in TerraME directory: In Windows: #> cd %TME_PATH%, in Linux: #> cd $TME_PATH. Execute the command #> terrame -version. In Windows and Linux only, the system will show the message: It is not possible to execute TerraME within its directory. Please, run it from another place.
Go to another directory and run the same previous command (terrame -version). The system will show the information about its version.
Run TerraME to show the graphical interface. Select TerraME Desktop icon in Windows. Run #> terrame command from an empty directory in Mac and Linux. A graphical interface should be shown with nine buttons (three disabled) and four comboboxes (two disabled).
Click in About. A message should be shown with the description of base package.
Click in Documentation. A web browser should be open with the main documentation of TerraME. The Release field must be today or yesterday.
Select example sir-basic and then click Run. A chart should be shown with three lines.
Close the chart. The focus will come back to the graphical interface.
Select example deforestation and click in Run. Amazonia will be shown as three Maps simulating deforestation.
Close the maps. The focus will come back to the graphical interface.
Click in Install package. Select package sysdyn and press Install. Install,Install All and Close button will be disabled. A message will be shown: Package 'sysdyn' successfully installed. One additional dependency package was installed: - 'sci'.
Click in OK. The package sysdyn and sci (already installed) will be shown in package's list.
Click in Close The main screen will be enabled again. Package sysdyn will be selected.
Download the latest version of ca package from here. Click in Install local package, select the downloaded package and then click in Open. A message will be shown: Package 'ca' successfully installed. After pressing OK, package ca will be selected and Configure button will be enabled.
Click in Install package. Select package ca. Install button will be disabled. The main screen will be disabled.
Click Close. Select model Fire. Click in Configure. Set Emtpy to 0.2. Click Run. A chart and a map will be shown with the simulation of fire in the forest model.
Close the chart and map. Click in Quit to close the configuration of Fire. Click in Install package. Click in Install All. Install,Install All and Close button will be disabled. The following message will be shown: Package 'logo' successfully installed. If there are more available packages, the message will say that such packages were also installed.
Click in OK. All packages (already installed) will be shown in package's list. Install All button will be disabled.
Click in Close. The main screen will be enabled again. Package ca will still be selected.
Click in About. A message should be shown with the description of ca package.
Click in Documentation. A web browser should be open with the main documentation of ca package.
Select package gis and repeat the two previous commands. The same results for such package. The Release field must be today or yesterday.
Select project cabecadeboi. Click in Create. Click in Run. Creates a database. Itambe do Mato Dentro (Minas Gerais) will be shown as a Map.
Close the map. Click again in Create. Set the Resolution to abc. Click in Run. An error message will be shown: Error: Resolution must be a number.
Click in OK. Set the Resolution to 200. Click in Run. Creates a new database with a different resolution and it will be shown as a Map.
Close the map. The focus will come back to the graphical interface.
Select package publish. Select example caragua. Click Run. Click OK. Wait some time and then a message will be shown saying that the project was created. A web page will be shown with the created application.
Close the browser and then click OK. Wait some time and then the buttons will be enabled again to indicate that the example has finished.
Click in Create All. Press OK. Five projects will be created within data directory of package publish.
Click OK. Select package sysdyn. The list of projects will be clean.
Select Model PredatorPrey. Click in Configure. Change Final Time to 200. Click in Run. Two charts will be shown side by side, one with a circular red shape and the other with two lines for rabbits (red) and wolves (green).
Close the two charts. Change Final Time to 100. Click in Run. Two charts will be shown in the same location of the previous simulation.
Close the two charts. Click in Quit to close the configuration of PredatorPrey. Select Model SIR. Click in Configure. Click in Run. A chart will be shown with three lines (susceptible, infected, and recovered).
Close the chart and click Quit to close the configuration of SIR. Close the wireless connection (if any) and remove the network cable (if connected). Press Install package. An error message will be shown: Could not download the package list. [...].
Connect the Internet again and click in Install package one more time. All packages (already installed) will be shown normally.
Close Install package and press Quit button. TerraME will ask if you want to delete nine files and one directory that were created during the execution of the graphical interface (four Lua files, one qgs, two tview, and two shapefiles).
Unselect SIR-instance.lua and cabecadeboi.shp and then click Delete Selected. TerraME should exit without any error. The current directory should contain SIR-instance.lua, cabecadeboi.shp, and other four files related to cabecadeboi.shp (with extensions shx, dbf, qix, and prj).
If Windows, uninstall TerraME by Uninstall icon. The directory where TerraME was installed must be removed.

After executing these visual tests, execute visual tests related to ZeroBrane.

Test procedure Expected results
Install the latest version of ZeroBrane. ZeroBrane should be successfully installed.
Follow the steps in the tutorial to configure ZeroBrane. Everything should work properly.
Execute Project->Package Manager from the main menu. TerraME main screen must be shown.
Press Quit. TerraME should quit without any error.
Download the latest version of sci package here and unzip it into a local directory. Open the file description.lua within package sci in ZeroBrane. File displayed in the main screen.
Execute Project->Documentation sketch from the main menu. TerraME runs -sketch with the package. The final report has no errors and it starts with Sketch report ...
Execute Project->Build documentation from the main menu. TerraME runs -doc with the package. The final report has no errors and it starts with Documentation report ...
Execute Project->View documentation from the main menu. The documentation of package sci will be shown in a webpage.
Execute Project->Run tests from the main menu. TerraME runs -test with the package. The final report has no errors and it starts with Functional test report ...
Execute Project->Check package from the main menu. TerraME runs -check with the package. The final report has no errors and it starts with Code analyzer report ...

Source Code Style

Why should we use style and conventions

According to our references:

  • One way in which we can keep the code base manageable is by enforcing consistency. It is very important that any programmer be able to look at another's code and quickly understand it.
  • 80% of the lifetime cost of a piece of software goes to maintenance.
  • Hardly any software is maintained for its whole life by the original author.
  • Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
  • As every C++ programmer knows, the language has many powerful features, but this power comes with complexity, which in turn can make code more bug-prone and harder to read and maintain.

Lua

This section describes some rules to write Lua source code in TerraME. Its main usage is for TerraME developers, but it can also be used by modelers in general or package developers.

I: Source code should use tabs instead of spaces.

II: Source code should be written in english, even comments.

III: Source code should not contain any special character such as á or õ.

IV: After every comma there should exist an empty space or an end of line. Before the comma, there should not exist any space. This rule has priority over any other rule.

V: There should not exist empty space before opening a parenthesis. In the same way, there should not exist any empty space before closing parenthesis. The same rule is applied for brackets and braces.

VI: Second order functions should use only one indentation, as it adds only one scope. All arguments should be declared in the first line, with the function being the last argument. The last line of the second order function should have end), in the following way:

forEachNeighbor(cell, "id", function(neighbor)
    neighbor.value = neighbor.value + 1
end)

VII: Strings should always be described with double quotes ("). Inside of strings, single quotes (') should be used when necessary. For example:

customError("Package '"..package.."' is not installed.")

VII: Assign operator (=), logic operators (==, >, <, etc.), and arithmetic operators (+, -, *, etc.) should follow and be follwed by an empty space. Additionally, it is possible to have such operators as the first valid character of a line, but not as the last one. For example:

expected =  - 0.450 * math.log(cell.distRoads)
            + 0.260 * 1 / cell.distPorts
            - 0.140 * cell.protectedArea
            + 5.313

IX: Parenthesis inside of if should be avoided when possible. Note that if does not require parenthesis in Lua.

X: Small ifs with only one command can be written in only one line.

XI: Never use else if when there is a single if in the else. Use elseif instead.

XII: Every then should be written in the same line of the if.

XIII: Every for that has an increment of one should ommit the third argument after =, as it is the default value.

XIV: Operators #, ., .. and : should not be preceded by empty space.

XV: Tables with only one attribute should be written in a single line. Tables with two attributes can have its attributes described in different lines. Tables with three or more attributes should have each attribute described in a separate line. One exception is when there are different tables with the same attributes, where all them can be described in a single line to simplify reading.

XVI: Point and comma should not be used in the source code, unless when separating commands in a single line.

XVII: There should not exist an empty line separating two elements of a table, even when the table defines a new type.

XVIII: There should not exist two blank lines in sequence.

XIX: Although possible, comma after the last element of a table should be removed.

XX: Every line should have up to 100 characters. Exceptions are allowed when there is a large arithmetical operation or string.

XXI: Elements of a table with a constant value should not be written using brackets. Use . instead. This way, the following code:

switch(data, "strategy"): caseof {
    ["probability"] = function()  
        checkUnnecessaryArguments(data, {"strategy"})
    end,
    ["quantity"] = function()
        checkUnnecessaryArguments(data, {"strategy"})
    end
}

should be written as:

switch(data, "strategy"): caseof {
    probability = function()  
        checkUnnecessaryArguments(data, {"strategy"})
    end,
    quantity = function()
        checkUnnecessaryArguments(data, {"strategy"})
    end
}

XXII: Every file should end with an empty line.

XXIII: Every comment should have an empty space following --.

XXIV: After a line that stops the simulation with one error there should not exist any command but an end.

XXV: Every line that contains an end should obey one and only one of the rules below:

  • end with a comma (,)
  • be followed by an empty line,
  • be followed by a line with elseif, else, or another end.

XXVI: Every line that contains a } should be follwed by an empty line, or by a line that ends with another } (unless the table was started in the same line).

XXVII: An empty line should be used in the end of a group of commands, not in the beginning. For example, there should not exist an empty line just after the declaration of a function, or between a comment and the source code it refers.

XXVIII: Global functions should be declared without using =. This way, code below:

round = function(...) end

should be:

function round(...) end

XXIX: Functions of a file should be declared in alphabetical order whenever possible.

C++

TerraME C++ code uses Google C++ Style Guide with some clearance. Not all rules are mandatory and some are cutomized. The TerraME is build in OO paradigm, so another style that help is Code Conventions for the Java Programming Language. There are similar rules for other programming languages. Although Google Style is our main reference, the naming rules aren't cool. We prefer Java, just remember that Java has its peculiarities, so you will not to need them. Java has others cool things that you can use in C++. So read up all stuff and free your mind!

Coming back to Google C++ Style Guide, only customized and not mandatory rules will be described here. The rest is mandatory. Remember all code must be written in English, don't forget this. The customised and not mandatory rules are as follows:

Section Rule
Header Files The #define Guard (The format of the symbol name should be CLASSNAME_H, composite name CLASS_NAME_H.)
Classes Explicit Constructors (Not mandatory) Interfaces (Use Interf suffix instead Interface. Note that the suffix not is mandatory)
Google-Specific Magic Ownership and Smart Pointers (Not mandatory)
Other C++ Features Exceptions (Not mandatory) Preincrement and Predecremen (Not mandatory) Use of constexpr (Not mandatory)
Naming Use Java Code Conventions instead
Comments Use the comments rules but together the syntax rules of the tool of documentation generator [to be defined]
Formatting Feel free to use Google or Java, both are cool. Line Length (Use 80 columns but with tolerance 90 at worst 100) Spaces vs. Tabs (Use tabs for indentation. Beware with fonts non-monospaced in IDE) Function Calls (Adjust with tabs and space not use only space) Conditionals (You must use also brace "{" in line below if). Loops and Switch Statements (Same as before also to for, while, switch, etc.) Class Format (Do not use space before the keywords. You can use the same rule of brace "{" here too) Constructor Initializer Lists (Use tab and space not only spaces.) Namespace Formatting (You can use the same rule of brace "{" here too)

Committing

Whenever one or more lines of a source code file is changed, the Github client shows them as uncommited.

Every commit using Git is local. It means that if you remove the root directory after some commits you will loose all the implementation. After finishing a set of commits that conclude a given job, it is possible to push the commits to Github. It is mandatory that only code that passes in all tests should be commited.

Commits must refer to a given issue by including #. For example, if one writes:

Close #1234. Function '+' implemented.

It is also possible to refer to an issue without closing it by ommiting Close before the issue number. It is recommended to add a reference to the issue in the beginning of the text because it guarantees that the issue number will also be shown in github (large texts will have an "..." in Github's screen).

After that, you can send the changes to you fork in Githun by clicking in Push in Sourcetree. Note that these changes will update only your fork, but not TerraME's master fork.

Pull Request

To put your changes into TerraME's master fork, it is necessary to create a Pull request. Go to your fork's webpage in Github. It will have a message such as This branch is X commits ahead TerraME:master. If it also has Y commits behind [...], you will need to update your fork to keep your pull request consistent. Follow the steps below to configure SourceTree:

  1. Open your forked repository in SourceTree.
  2. Select Repository and then Repository Settings… in the menu.
  3. In the Remotes pane, press Add.
  4. Enter any name you like (often upstream or master) and the URL/path to the parent repository (in this case, https://github.com/TerraME/terrame.git).
  5. Press OK, then OK.

The steps above will only need to be configured once, unless you remove and download your repository again. Now, to update your fork:

  1. Select Pull in the toolbar.
  2. In the Pull from repository drop-down, switch from your fork to the repo you just added.
  3. Press OK.
  4. Eventually you will need to solve conflicts. If you have any doubts in this step, please contact the project admin to help you.
  5. Push the new content up to your fork in Github.

After updating your fork, there is no longer a comment Y commits behind [...] in your fork. Click in the Pull request` button in the main page of your fork in Github. Configure the pull request with the following parameters:

  • The name of the pull request must follow <your own name>'s updates to <the milestone version> - part <your-counter>. For example, if Bart creates his second pull request for the release 1.0, the name would be Bart's updates to 1.0 - part 2.
  • The milestone will be the same of the issues. If you are solving an issue scheduled to a future release, change its release to the current one.
  • The assignee must be the project admin.
  • The issues you are solving in the pull request must belong to the description of the pull request, in the following form:
- [ ] #first issue
- [ ] #second issue
- [ ] [...]

As an example, click here. Note that it is possible to edit the description, adding or removing issues if needed. Typically a pull request should long between one or two weeks, so add only a set of issues that can be solved in this period. Once you get more experience with the pull request process, read OpenUP for more advanced strategies. See Practices -> Technical Practices -> Continuous Integration.

When this pull request is created, it will automatically activate Jenkins to execute all verifications and tests to validate the pull request. After some time, you will see the results of each of them. If there is any errors, you will need to update your code and push it into your repository again. Once you push new code, Jenkins will be automatically activated again by your pull request.

As long as you solve an issue, mark it as solved in the description of the pull request. Once everything is ok with your pull request, the project admin will merge it into Github. All issues with Close #issue will be automatically closed. A link in the issue will also be created so one can see the changes in the source code to finish such task.

If you have comments, doubts or suggestions related to this document, please write a feedback to pedro.andrade <at> inpe.br.

Back to wiki or terrame.org.

Clone this wiki locally