mirror of
https://github.com/stylersnico/librenms.git
synced 2026-07-27 00:25:06 +02:00
Daniel Preussker
@@ -48,3 +48,5 @@ Ensure you use <?php rather than the shorthand version <?.
|
||||
```php
|
||||
<?php
|
||||
```
|
||||
|
||||
The `?>` tag isn't required for included php files. For instance anything in includes/ or html/includes don't need the tag along with config.php. If the php file is standalone then you still need the tag. If you are unsure, add it in :)
|
||||
|
||||
@@ -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 `<li role="presentation" class="divider"></li>`.
|
||||
|
||||
- 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.
|
||||
@@ -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
|
||||
@@ -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"
|
||||
|
||||
Reference in New Issue
Block a user