Changes between Version 16 and Version 17 of DRM4G/Development


Ignore:
Timestamp:
Dec 12, 2016 8:03:28 PM (5 years ago)
Author:
minondoa
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DRM4G/Development

    v16 v17  
    22Contributing
    33If you want to contribute to this repository please be aware that this project uses a gitflow workflow with the next release branch called next.
     4* You can find the project [[https://github.com/SantanderMetGroup/DRM4G|here]].
     5
    46Please fork this repository and create a local branch split off of the next branch and create pull requests back to the origin next branch.
    5 We [try/strive/] to adopt a DevOps [development methodology/set of practices].
     7
     8We [try/strive/] to adopt a !DevOps [development methodology/set of practices].
    69}}}
    710[[TOC(heading=Development)]]
    8 = Development =
     11
     12= Contributing for users =
     13
     14To make it easier and more accessible for anyone to play around with the DRM4G, we have decided to host our source code on **!GitHub**.
     15
     16If you want to contribute to this repository please be aware that this project follows a certain [#OurGitworkflow gitflow].
     17
     18So please fork this repository and create a local branch in which to do your work, and then create a pull requests to the main DRM4G repository.
     19
     20[[br]]
     21
     22== Necessary Steps ==
     23For those of you who wish to help but don't know how, the  first thing you need is a [[https://github.com/join?source=header-home|GitHub account]].
     24
     25In our project's page hit the "'''''Fork'''''" button at the top right corner:
     26
     27[[Image(fork_button.png)]]
     28
     29This will create a copy of our repository in your account where you'll develop your own feature or implement a bugfix that you may believe is necessary. You'll be submitting changes to this one until you are certain everything works properly, at which point you can request to have your changes integrated into the DRM4G's repository.
     30
     31To continue, you'll need to setup a local repository where you'll be changing the code and doing your testing. To do this you'll need your repository URL, that can be obtained adding '''.git''' to your project page or by clicking on the "'''''Clone or download'''''" button:
     32
     33
     34[[Image(clone_button.png)]]
     35
     36
     37In Linux operating systems:
     38* Open a terminal on the folder in which you wish your local copy of the repository to be stored (it's recommended to use an empty folder) and run the following commands:
     39
     40{{{#!sh
     41git init  #to initialize an empty Git repository
     42git remote add origin <your_repository_url> #to make your local repository point to your remote repository in GitHub
     43git fetch
     44git checkout develop #to create a local copy of the develop branch
     45}}}
     46
     47To be consistent with our [wiki:DRM4G/Development#OurGitworkflow gitflow], all you'll be able to do is create '''feature or bugfix branches''', and you'll have to follow our naming conventions to do so.
     48* Our !GitHub's default branch is "'''develop'''", and this is done intentionally, since the "'''master'''" will only be updated when publishing a new release
     49 * __This means that all pull requests to the "'''master'''" branch will be rejected__
     50* The naming convention will just be to create branches in lower case letters separated by underscores ("'''_'''") that describe what you're trying to accomplish with the branch.
     51
     52With this, you will now have DRM4G's source code at your disposal.
     53
     54{{{#!comment
     55There are a lot of tutorials showing how to use git, including [[wiki:versionControl/git|our own]], but here is a more specific one, a simple step by step explanation on how to start using it to help us improve DRM4G.
     56}}}
     57
     58From here you could create branches for every new feature you'd like to include to the DRM4G, for a more in depth tutorial on how to do that, click [[https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging|here]].
     59
     60
     61[[br]]
     62
     63== Testing the DRM4G
     64Once you've made the changes you wanted to, you'll want to install your version to be sure that your new feature is working properly.
     65
     66Just in case you would like to try out different versions, we recommend you use a __virtual environment__ to test it.
     67
     68 * [[http://pythoncentral.io/how-to-install-virtualenv-python/|Here]] you can find a tutorial on how to install a virtual environment, or you can look for one on your own.
     69
     70Before you can install and try out your own version, you'll have to build your own package:
     71* Open a terminal in the folder where your repository is located.
     72* Run the command `python setup.py sdist`
     73
     74This will create a a distribution package under a folder called '''dist'''.
     75
     76
     77=== Installing your version in a virtual environment ===
     78
     79Go to wherever you have your virtual environment, open a terminal and execute the following commands:
     80
     81{{{#!sh
     82source bin/activate
     83export DRM4G_DIR = $PWD/conf
     84pip install path/to/drm4g/package
     85}}}
     86 ^DRM4G_DIR is where the configuration files will be installed. More information [[wiki:DRM4G/Installation#OptionalEnvironmentVariables|here]].^
     87
     88And that's it. Now you can use and test your own version of DRM4G.[[BR]]
     89
     90'''''For other ways to install the DRM4G, you can check [[wiki:DRM4G/Installation|here]].'''''
     91
     92
     93[[br]]
     94
     95== Commiting changes
     96
     97After you've tested that everything is in working order, it's time to update your !GitHub fork.
     98
     99{{{#!sh
     100git add .
     101git commit -m "Description of the changes you've made"
     102git push origin develop
     103}}}
     104{{{#!comment
     105Creo que esto ya no hace falta, al hacer el "git checkout" ya se empieza a monitorizar la rama remota
     106git push -u origin develop #just the first time, the following times just run "git push origin develop"
     107}}}
     108
     109
     110From here you'll have to create a '''Pull request'''.
     111
     112
     113[[br]]
     114
     115== Creating a Pull Request ==
     116
     117As time passes, chances are that the main DRM4G repository has had other contributors merge changes into it, so you should first update your local repository and check that there are no conflicts.
     118
     119{{{#!sh
     120git checkout develop
     121git remote add github https://github.com/SantanderMetGroup/DRM4G.git #just do run this command the first time to add the main repository to the list of your remotes
     122git pull github develop
     123}}}
     124
     125If there have been any changes, but there are no conflicts, you can just ''push'' your changes into your remote repository.
     126
     127{{{#!sh
     128git push origin develop
     129}}}
     130
     131In the case that there are conflicts, resolve them and commit the changes, after do the ''push'' to update your remote repository.
     132
     133After, you just have to go to your repositories web page and click on the "'''''New pull request'''''" button.
     134
     135
     136[[Image(pull_request_button.png)]]
     137
     138A message will tell you if there are any conflicts that need to be solved or if an automatic merge is possible. Then you just have to click on the "'''''Create pull request'''''", give this merge a title (which will serve as the commit message if the pull request is accepted), a comment if you want (can be useful to explain in more detail why this should be integrated into the DRM4G), and click a second time on the "'''''Create pull request'''''" button.
     139
     140Now you'll have to wait and see if the administrator of the project accepts the changes you're proposing.
     141
     142{{{#!comment
     143From your project repository
     144For more information on how to use git
     145}}}
     146
     147----
     148
     149Another option would be to create a new branch from the "'''develop'''" branch and then try to make a pull request from that.
     150
     151{{{#!sh
     152git checkout develop
     153git checkout -b new_branch
     154#make some changes
     155git add .
     156git commit -m "Description of the changes you've made"
     157git push origin new_branch
     158}}}
     159
     160The next time you enter your repository's web page, you'll see a new button:
     161
     162[[Image(pull_request_new_branch.png)]]
     163
     164Click on "'''''Compare & pull request'''''" to perform a pull request on to the main repository. The same will happen as when clicking on "New pull request" when on a previously existing branch.
     165
     166
     167
     168[[br]]
     169
     170[[br]]
     171
     172= Contributing for developers =
    9173The aim of this section will be to explain the process we follow to contribute to the development of the DRM4G.
    10174
     
    12176We use something similar to a [http://nvie.com/posts/a-successful-git-branching-model/ gitflow] workflow. Internally we synchronize our work with **!GitBucket**, which is what will be considered as the  '''''central repository''''' of the '''Santander Meteorology Group'''.
    13177* You can find the project [https://meteo.unican.es/gitbucket/DRM4G/DRM4G here], but to be able to access it you must first get a [https://meteo.unican.es/gitbucket/register GitBucket account] and get access to the private repository.
     178* Have in mind that we try to adopt the !DevOps development methodology.
    14179
    15180[[br]]
     
    278443
    279444At the end, the last step is to update the [wiki:DRM4G/ChangeLog realese wiki page] and the references in the section "[wiki:DRM4G#Newreleases New releases]" of the DRM4G's main wiki page.
     445
     446
     447
     448[[br]]
     449
     450== Managing the !GitHub account ==
     451For the administrator of the DRM4G's !GitHub repository:
     452
     453When you see that there's a new pull request, either because you saw it on the projects page or because you received a message in your mail informing you about it, you can click on the "'''''Pull requests'''''" button.
     454
     455[[Image(view_pull_requests_button.png)]]
     456
     457
     458* If you agree with the changes made, and there are no conflicts, you can just click on the "'''''Merge pull request'''''" button.
     459 * You'll automatically see a commit message that will look something like this: "__Merge pull request #X from <contributor>/<branch_name>__"
     460 * Bellow that, you can write an "optional extended description".
     461  * When running `git log` from the command line, you'll just see both lines shown as the commit message.
     462 * When done just click on the "'''''Confirm merge'''''" button to finish.
     463* If don't agree or there are conflicts, you can click right next to the "Merge pull request" button, where it says "'''''command line instructions'''''" to perform a manual merge.
     464 * Just follow the instructions shown there.
     465 * Optionally, you could also try to solve the conflicts wiht the web editor, but this isn't recommended since you can't test what you're changing, unless the conflict is in a comment or a text message, not in the code.
     466
     467[[Image(merge_pull_request_button.png)]]