1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
1 |
====== Files - Contribute ====== |
2 |
||
3 |
**This document is licensed under the LGPL 2.1.** |
|
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
4 |
This document is based on the HACKING file from the Midori browser project. |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
5 |
|
6 |
====== Testing the latest build ====== |
|
7 |
||
8 |
Get daily builds in Launchpad (https://launchpad.net/~elementary-os/+archive/daily ppa:elementary-os/daily). |
|
9 |
||
10 |
====== Join IRC chat rooms ====== |
|
11 |
||
12 |
Join #elementary-dev on Freenode: https://kiwiirc.com/client/irc.freenode.net/elementary-dev. |
|
13 |
||
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
14 |
====== Contribute without touching code ====== |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
15 |
|
16 |
- http://bugs.launchpad.net/pantheon-files Go through problem reports and check Unconfirmed bugs or those lacking information and mark any duplicates you spot. |
|
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
17 |
- https://translations.launchpad.net/pantheon-files Help getting Files translated in your language! |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
18 |
|
19 |
====== Check out the sources ====== |
|
20 |
||
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
21 |
bzr branch lp:pantheon-files |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
22 |
|
23 |
The development **trunk** (master, tip) is the latest iteration of the next release. |
|
24 |
Browse it online and look for other branches at http://code.launchpad.net/pantheon-files |
|
25 |
||
26 |
====== Build the code ====== |
|
27 |
||
28 |
Refer to INSTALL for required dependencies. |
|
29 |
||
1266.2.3
by Julián Unrrein
More improvements. |
30 |
Then: |
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
31 |
mkdir build |
32 |
cd build |
|
33 |
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug |
|
34 |
make |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
35 |
|
36 |
Run Files: |
|
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
37 |
./src/pantheon-files |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
38 |
|
1266.2.5
by Julián Unrrein
Improve HACKING. |
39 |
To run Files from a local branch, you will need to already have Files installed in your system, since configuration files and plugins are loaded from system directories. |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
40 |
|
1266.2.3
by Julián Unrrein
More improvements. |
41 |
If you'd like to install from your local branch: |
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
42 |
sudo make install
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
43 |
|
44 |
====== Debugging issues ======
|
|
45 |
||
46 |
Testing an installed release may reveal crashers or memory corruption which require investigating from a local build and obtaining a stacktrace (backtrace, crash log).
|
|
47 |
||
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
48 |
gdb ./src/pantheon-files
|
49 |
run --debug
|
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
50 |
|
51 |
====== Coding style and quality ======
|
|
52 |
||
1266.2.5
by Julián Unrrein
Improve HACKING. |
53 |
Be sure to check the official elementary Code Style guide at:
|
1302.1.1
by Julián Unrrein
Point to the official elementary Code style guide. |
54 |
http://elementaryos.org/docs/code/code-style
|
1266.2.5
by Julián Unrrein
Improve HACKING. |
55 |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
56 |
Files' code should in general have: |
57 |
||
58 |
* 4 space indentation, no tabs. |
|
59 |
* Between 80 to 120 columns. |
|
60 |
* Prefer /* */ style comments. |
|
61 |
* Call variables //animal// and //animal_shelter// instead of <del>camelCase</del>. |
|
62 |
* Keep a space between functions/ keywords and round parentheses. |
|
63 |
||
64 |
For Vala: |
|
65 |
||
66 |
* Prefer //new Gtk.Widget ()// over //using Gtk; new Widget ()// |
|
67 |
* No necessity to prefix anything from the GLib namespace. An exception to this rule is when using GOF.File and GLib.File in the same source file. |
|
68 |
* Stick to standard Vala-style curly parentheses on the same line |
|
69 |
* Cuddled //} else {// and //} catch (Error error) {// |
|
70 |
||
71 |
For C: |
|
72 |
||
1266.2.3
by Julián Unrrein
More improvements. |
73 |
* Always keep { and } on their own line. |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
74 |
|
1289.1.1
by Julián Unrrein
Add documentation to warn developers that only one fix is to be done for each branch when possible. |
75 |
====== Important: Keep fixes for different bugs in different branches ====== |
76 |
||
77 |
Branches that contain patches to fix more than one bug will be rejected, and you will be asked to supply a separate branch for every bug fix. |
|
78 |
This doesn't apply to patches that are indivisible by nature, and that fix multiple bugs. |
|
79 |
||
80 |
The reasons to work in this way are the following:
|
|
81 |
||
82 |
* If one of the bugs targeted by your branch is correctly fixed, but one of the other bugs is incorrectly fixed or needs corrections, the branch won't be accepted until everything looks ok for all bugs. This causes an unnecessary delay for the bugs that where fixed correctly. |
|
83 |
* Suppose your branch was accepted for merging in the main one. Later, it is discovered that your branch introduces faulty behavior. The standard course of action for these situations is to revert the merge that introduced that faulty behavior. This will cause that all of your fixes are reverted (even the ones that didn't cause problems) because there was no way of discriminating between them. If a separate branch for each bug fixed existed, only the offending one would have been reverted, and not all of them. |
|
84 |
||
85 |
Be sure to understand this, and avoid a headache later!
|
|
86 |
||
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
87 |
====== Committing code ======
|
88 |
||
1289.1.1
by Julián Unrrein
Add documentation to warn developers that only one fix is to be done for each branch when possible. |
89 |
Make a branch which will contain your changes for fixing bug XXXX:
|
90 |
bzr branch lp:pantheon-files fix-XXXX
|
|
91 |
||
1266.2.3
by Julián Unrrein
More improvements. |
92 |
Tell Bazaar your name if you haven't yet: |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
93 |
bzr whoami "Real Name <email@address>" |
94 |
||
1266.2.3
by Julián Unrrein
More improvements. |
95 |
See what you did so far: |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
96 |
bzr diff |
1266.2.3
by Julián Unrrein
More improvements. |
97 |
bzr diff | colordiff |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
98 |
|
1266.2.3
by Julián Unrrein
More improvements. |
99 |
Get an overview of changed and new files: |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
100 |
bzr status |
101 |
||
1266.2.3
by Julián Unrrein
More improvements. |
102 |
Add new files, move/ rename or delete: |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
103 |
bzr add FILENAME |
104 |
bzr mv OLDFILE NEWFILE |
|
105 |
bzr rm FILENAME |
|
106 |
||
1302.1.2
by Julián Unrrein
Clarify what it means to commit work to the branch. Add reference to the "bzr revert" command. |
107 |
After making your changes, you need to commit your work as a new revision. |
108 |
bzr commit -m "Commit message" |
|
109 |
||
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
110 |
Commit your changes in small increments. It is better to keep different changes in different commits. |
111 |
||
1266.2.3
by Julián Unrrein
More improvements. |
112 |
To see the last 5 revisions in the current branch: |
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
113 |
bzr log -l5 |
114 |
bzr log -l5 -p | less |
|
115 |
||
116 |
In the case you committed something wrong or want to ammend it: |
|
117 |
bzr uncommit |
|
1302.1.2
by Julián Unrrein
Clarify what it means to commit work to the branch. Add reference to the "bzr revert" command. |
118 |
|
119 |
If you want to revert all the changes made after the last revision: |
|
120 |
bzr revert |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
121 |
|
122 |
Remember to keep your branch updated: |
|
123 |
bzr pull |
|
124 |
||
125 |
As a general rule of thumb, ''bzr help COMMAND'' gives you an explanation of any command and ''bzr help commands'' lists all available commands. |
|
126 |
||
127 |
//If you're a die-hard git user, http://zyga.github.io/git-lp/ checkout git-lp to use git commands with the Bazaar repository.// |
|
128 |
||
129 |
====== Push proposed changes ======
|
|
130 |
||
131 |
If you haven't yet, https://launchpad.net/~/+editsshkeys check that Launchpad has your SSH key - you can create an SSH key with **Passwords and Keys** aka **Seahorse** or ''ssh-keygen -t rsa'' - and use ''bzr launchpad-login'' to make youself known to bzr locally. |
|
132 |
||
133 |
If you checked out trunk, and added your patch(es), just **push it under your username** in Launchpad and you can **propose it for merging into trunk**. This will automatically request a **review from other developers** who can then comment on it and provide feedback. |
|
134 |
||
1289.1.1
by Julián Unrrein
Add documentation to warn developers that only one fix is to be done for each branch when possible. |
135 |
bzr push lp:~USERNAME/pantheon-files/fix-123456 |
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
136 |
bzr lp-open |
137 |
||
138 |
The last command will open a summary of the current branch in your web browser. There, you will be able to propose it for merging into trunk. |
|
1302.1.4
by Julián Unrrein
Give some notion about how the review process works. |
139 |
Your branch will be reviewed by another developer. At this stage, you may be notified that changes need to be made to your branch, so keep an eye on your email inbox! |
140 |
After the branch is approved by the reviewer, it will get merged into the main project's source code. |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
141 |
|
1266.2.3
by Julián Unrrein
More improvements. |
142 |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
143 |
**What happens to all the branches?**
|
144 |
||
145 |
Leave the branches alone, **approved branches are cleared automatically** by Launchpad.
|
|
146 |
||
147 |
For larger feature branches, **use the team** in Launchpad to allow other developers to work on the code with you.
|
|
148 |
||
1266.2.3
by Julián Unrrein
More improvements. |
149 |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
150 |
What if I want to help out on an **existing merge request** that I can't push to? |
151 |
||
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
152 |
bzr branch ~OTHERPERSON/pantheon-files/fix-123456 |
153 |
cd fix-123456 |
|
154 |
# make commits |
|
155 |
bzr push lp:USERNAME~/midori/fix-123456 |
|
156 |
bzr lp-open |
|
157 |
||
158 |
And in the Launchpad web overview of your branch, propose your branch for merging into ~OTHERPERSON/pantheon-files/fix-123456 |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
159 |
|
1266.2.3
by Julián Unrrein
More improvements. |
160 |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
161 |
Updating a branch that may be out of sync with trunk: |
162 |
||
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
163 |
bzr pull |
164 |
bzr: ERROR: These branches have diverged |
|
165 |
bzr merge lp:pantheon-files |
|
166 |
# Hand-edit conflicting changes |
|
167 |
bzr resolve FILENAME |
|
168 |
# If any conflicts remain continue fixing |
|
169 |
bzr commit -m 'Merge changes from lp:pantheon-files' |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
170 |
|
1266.2.3
by Julián Unrrein
More improvements. |
171 |
|
1266.2.1
by Julián Unrrein
Improve the INSTALL file. Remove content from TODO. Add content to README. Add new file HACKING. Remove empty NEWS file. |
172 |
Save a little bandwidth, **branch from an existing local copy** that you keep around: |
173 |
||
1266.2.2
by Julián Unrrein
Improve documentation content and style. |
174 |
bzr branch lp:pantheon-files pantheon-files |
175 |
bzr branch pantheon-files files-fix-123456 |
|
176 |
cd files-fix-123456 |
|
177 |
bzr pull lp:pantheon-files |