From 790825efa36cbc38ce1a68cf938b9e5e1f3d1cdf Mon Sep 17 00:00:00 2001 From: laf Date: Tue, 5 May 2015 22:17:22 +0100 Subject: [PATCH] Updated development docs --- doc/Developing/Code-Guidelines.md | 2 + doc/Developing/Style-Guidelines.md | 40 +++++++++++ doc/Developing/Using-Git.md | 108 +++++++++++++++++++++++++++++ doc/General/Contributing.md | 50 +------------ 4 files changed, 152 insertions(+), 48 deletions(-) create mode 100644 doc/Developing/Style-Guidelines.md create mode 100644 doc/Developing/Using-Git.md diff --git a/doc/Developing/Code-Guidelines.md b/doc/Developing/Code-Guidelines.md index 2d59bb875..9bca5ac41 100644 --- a/doc/Developing/Code-Guidelines.md +++ b/doc/Developing/Code-Guidelines.md @@ -48,3 +48,5 @@ Ensure you use ` tag isn't required for included php files. For instance anything in includes/ or html/includes don't need the tag along with config.pgp. If the php file is standalone then you still need the tag. If you are unsure, add it in :) diff --git a/doc/Developing/Style-Guidelines.md b/doc/Developing/Style-Guidelines.md new file mode 100644 index 000000000..cef63a7ee --- /dev/null +++ b/doc/Developing/Style-Guidelines.md @@ -0,0 +1,40 @@ +# Style guidelines + +This document is here to help style standards for contributions towards LibreNMS. These aren't strict rules but it is in +the users interest that a consistent well thought out Web UI is available. + +### Responsiveness + +The Web UI is designed to be mobile friendly and for the most part is and works well. It's worth spending sometime to +read through the [Boostrap website](http://getbootstrap.com/css/#grid) to learn more about how to keep things responsive. + +### Navigation bar + +- Always pick the best location for new links to go, think about where users would expect the link to be located and name +it so that it's obvious what it does. + +- Ensure sub sections within the Navigation are separated correctly using ``. + +- Only use [Font Awesome icons](http://fontawesome.io/icons/) within the Navigation. It speeds up page load times quite +considerably. + +### Buttons + +Try to keep buttons colored to reflect the action they will take. Buttons are set using Bootstrap classes. The size of +the buttons will depend on the area of the website being used but btn-sm is probably the most common. + +- Delete / Remove buttons: btn btn-danger + +- Edit / Update buttons: btn btn-primary + +- Add / Create buttons: btn btn-success + +### Tables + +Unless the table being used will only ever display a handful of items - yeah that's what we all said, then you need to +write your table using [JQuery Bootgrid](http://www.jquery-bootgrid.com/). This shouldn't take that much more code to +do this but provides so much flexibility along with stopping the need for retrieving all the data from SQL in the first +place. + +As an example pull request, see [PR 706](https://github.com/librenms/librenms/pull/706/files) to get an idea of what +it's like to convert an existing pure html table to Bootgrid. \ No newline at end of file diff --git a/doc/Developing/Using-Git.md b/doc/Developing/Using-Git.md new file mode 100644 index 000000000..ae2dc43fa --- /dev/null +++ b/doc/Developing/Using-Git.md @@ -0,0 +1,108 @@ +Git can have a bit of a steep learning curve, stick with it as it is worth learning the [basics][1][2] at least. + +If you want to help develop LibreNMS and haven't really used Git before then this quick primer will help you get started. + +Some assumptions: + +- Work is being done on a Linux box. +- LibreNMS is to be installed in /opt/librenms +- You have git installed. +- You have a [GitHub Account](https://github.com/). +- You are using ssh to connect to GitHub (If not, replace git@github.com:/yourusername/librenms.git with +https://github.com/yourusername/librenms.git. + +** Replace yourusername with your GitHub username. ** + +#### Fork LibreNMS repo +You do this directly within [GitHub](https://github.com/librenms/librenms/fork), click the 'Fork' button near the top right. + +If you are associated with multiple organisations within GitHub then you might need to select which account you want to +push the fork to. + +#### Prepare your git environment +These are the defaults that are recommended. + +```bash +git config branch.autosetupmerge true +git config --global user.name "John Doe" +git config --global user.email johndoe@example.com +``` + +#### Clone the repo +Ok so now that you have forked the repo, you now need to clone it to your local install where you can then make the +changes you need and submit them back. + +```bash +cd /opt/ +git clone git@github.com:/yourusername/librenms.git +``` + +#### Add Upstream repo +To be able to pull in changes from the master LibreNMS repo you need to have it setup on your system. + +```bash +git remote add upstream https://github.com/librenms/librenms.git +``` + +Now you have two configured remotes: + +- origin: This is your repository, you can push and pull changes here. +- upstream: This is the main LibreNMS repository and you can only pull changes. + +#### Workflow guide +As you become more familiar you may find a better workflow that fits your needs, until then this should be a safe +workflow for you to follow. + +Before you start work on a new branch / feature. Make sure you are upto date. +```bash +cd /opt/librenms +git checkout master +git pull upstream master +git push origin master +``` + +Now, create a new branch to do you work on. It's important that you do this as you are then able to work on more than +one feature at a time and submit them as pull requests individually. If you did all your work in the master branch then +it gets a bit messy! + +Ideally you want to create your new branch name based of the issue number. So firstly create an issue on +[GitHub](https://github.com/librenms/librenms/issues) so that others are aware of the work going on. If the issue number +you created is 123 then use issue-123 as the branch name. + +```bash +git checkout -b issue-123 +``` + +Now, code away. Make the changes you need, test, change and test again :) When you are ready to submit the updates as a +pull request then commit away. + +```bash +git add path/to/new/files/or/folders +git commit -a -m 'Added feature to do X, Y and Z' +git checkout master +git pull upstream master +git push origin master +git checkout issue-123 +git pull origin master +git push origin issue-123 +``` + +If after do this you get some merge conflicts then you need to resolve these before carrying on. + +Now you will be ready to submit a pull request from within GitHub. To do this, go to your GitHub page for the LibreNMS +repo. Now select the branch you have just been working on (issue-123) from the drop down to the left and then click +'Pull Request'. Fill in the details to describe the work you have done and click 'Create pull request'. + +Thanks for your first pull request :) Now, that might have been a simple update, if things get a bit more complicated +then you will need to break down your pull request into separate commits (still a single pull request). This is usually +done when: + +- You want to add / update MIBS. Do this in a separate commit including the link to where you got them from. +- You are adding say 3 related features in one go, try and break them down into 3 separate commits. +- Icons for new OS support need to be added as a separate commit including a link to where you got the logo from. + +Ok, that should get you started on the contributing path. If you have any other questions then stop by our IRC Channel +on Freenode ##librenms. + +[1]: http://gitready.com +[2]: http://git-scm.com/book \ No newline at end of file diff --git a/doc/General/Contributing.md b/doc/General/Contributing.md index b23b7f54e..ef6bdd079 100644 --- a/doc/General/Contributing.md +++ b/doc/General/Contributing.md @@ -147,54 +147,8 @@ project. Proposed workflow for submitting pull requests ---------------------------------------------- -The basic rule is: don't create merge conflicts in master. Merges should be -simple fast-forwards from current master. - -Following is a proposed workflow designed to minimise the scope of merge -conflicts when submitting pull requests. It's not mandatory, but seems to -work well enough. - -We don't recommend git flow because we don't want to maintain separate -development and master branches, but if it works better for you, feel free -to do that, as long as you follow the golden rule of not creating merge -conflicts in master. - -Workflow: - -- Ensure you have auto rebase switched on in your gitconfig. -``` -[branch] - autosetuprebase = always -``` -- Fork the [LibreNMS repo master branch][2] in your own GitHub account. -- Create an [issue][3] explaining what work you plan to do. -- Create a branch in your copy of the repo called issue-####, where #### is - the issue number you created. -``` -git push origin master:issue-#### -git checkout issue-#### -``` -- Make and test your changes in the issue branch as needed - this might take - a few days or weeks. -- When you are happy with your issue branch's changes and ready to submit - your patch, update your copy of the master branch to the current revision; - this should just result in a fast forward of your copy of master: -``` -git checkout master -git pull -``` -- Rebase your issue branch from your clone of master; fix any conflicts at - this stage: -```` -git checkout issue-#### -git pull -```` -- Push your changes to your remote git hub branch so you can submit a pull - from your issue-#### branch: -```` -git push origin issue-#### -```` -- Submit a pull request for your patch from your issue-#### branch. +Please see the new [Using Git](http://doc.librenms.org/Developing/Using-Git/) document which gives you step-by-step +instructions on using git to submit a pull request. [1]: http://www.gnu.org/licenses/license-list.html "Free Software Foundation's license list"