[pitivi] docs: Update the info about git and hacking
- From: Alexandru Băluț <alexbalut src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pitivi] docs: Update the info about git and hacking
- Date: Sun, 11 Feb 2018 02:20:20 +0000 (UTC)
commit 72616b7d09cbc9440f85ca37eaec3c2bda31ac98
Author: Alexandru Băluț <alexandru balut gmail com>
Date: Fri Dec 22 15:25:03 2017 +0100
docs: Update the info about git and hacking
Differential Revision: https://phabricator.freedesktop.org/D1925
docs/Coding_style_guide.md | 85 +++++++++++++
docs/Command_line_tools.md | 4 +
docs/Development_workflow.md | 120 +++++++++++++++++++
docs/Git.md | 272 +++++++-----------------------------------
docs/Git_repositories.md | 74 ------------
docs/HACKING.md | 198 +++++++------------------------
docs/Pitivi_Love.md | 10 +-
docs/Test_suite_wishlist.md | 11 --
docs/Testing.md | 20 ++--
docs/sitemap.txt | 4 +-
10 files changed, 316 insertions(+), 482 deletions(-)
---
diff --git a/docs/Coding_style_guide.md b/docs/Coding_style_guide.md
new file mode 100644
index 0000000..450d77f
--- /dev/null
+++ b/docs/Coding_style_guide.md
@@ -0,0 +1,85 @@
+---
+short-description: Writing code that looks consistent
+...
+
+# Coding Style Guide
+
+We rely on the [Python Style Guide PEP-8](https://www.python.org/dev/peps/pep-0008/)
+
+The only exception to it is regarding the "80 columns" rule.
+Since Python is a very concise/compact language, we can afford to be
+a little bit more flexible on the line length than languages such as C.
+
+When deciding whether or not you should split your line when it exceeds
+79 characters, ask yourself: "Does it truly improve legibility?"
+
+What this translates to is:
+
+- Avoid having very long lines.
+
+- When the contents only slightly exceeds the 80 chars limit,
+consider keeping it on one line. Otherwise it just hurts legibility and
+gives a weird "shape" to the code.
+
+## Names
+The function names, method names and other class attributes should be
+small_caps_with_underscore. For example:
+``` python
+def some_function():
+ return ""
+
+class MyClass:
+
+ def a_really_important_method(self):
+ self.do_something()
+
+ @property
+ def water_level(self):
+ """The level of the water in meters."""
+ return self.__water_level
+```
+
+To illustrate how private a method or other class field is, prepend
+one or two underscores:
+``` python
+ class MyClass:
+
+ def public_method(self):
+ ...
+
+ def _protected_method(self):
+ ...
+
+ def __private_method(self):
+ ...
+```
+
+Unused arguments in methods should be prefixed with `unused_`.
+The most common place where this would happen is in callbacks from
+gobject signals. For example, below we don't use the second argument,
+but we do use `pad`.
+
+``` python
+ def __pad_added_cb(self, unused_element, pad):
+ self.do_something_with(pad)
+```
+
+The name of a callback method should:
+
+ - be prepended with two underscores since it's private
+ - be appended with `cb`
+
+``` python
+ class MyClass:
+
+ def some_method(self):
+ self.someobject.connect('event', self.__some_object_event_cb)
+
+ def __some_object_event_cb(self, object, arg):
+ print "our callback was called"
+```
+
+## Imports order
+You can guess the order of the imported modules by looking at some py files.
+The pre-commit hook has authority in this case as it will reorder the imports
+if the order is not good.
diff --git a/docs/Command_line_tools.md b/docs/Command_line_tools.md
index e4f5ed4..a288e76 100644
--- a/docs/Command_line_tools.md
+++ b/docs/Command_line_tools.md
@@ -1,3 +1,7 @@
+---
+short-description: A list of tools useful when developing Pitivi
+...
+
# Command line tools
This is a list of tools useful when developing Pitivi.
diff --git a/docs/Development_workflow.md b/docs/Development_workflow.md
new file mode 100644
index 0000000..30d69d1
--- /dev/null
+++ b/docs/Development_workflow.md
@@ -0,0 +1,120 @@
+---
+short-description: How we do it
+...
+
+# Development Workflow
+
+We use [Phabricator
+tasks](https://phabricator.freedesktop.org/tag/pitivi/) to track all
+bugs and feature requests. Feel free to open a task if you have found a
+bug or wish to see a feature implemented. If it already exists,
+subscribe to it to keep yourself updated with its progress. You can also
+subscribe to the entire project.
+
+## Picking a task to work on
+
+To get involved, you can start with tasks tagged [Pitivi tasks for
+newcomers](https://phabricator.freedesktop.org/tag/pitivi_tasks_for_newcomers/).
+It's best to get in touch with us on our IRC channel `#pitivi` on
+Freenode, to see if it's still meaningful.
+
+Once you decide, assign the task to yourself in Phabricator.
+
+
+## Fixing the task
+
+Next is the fun part where you implement your cool feature, or fix an
+annoying bug:
+
+
+### Create a new git branch
+
+Create a new branch with a relevant name in your local git repository.
+The name must start with the task ID.
+
+For example, if you're
+going to work on task [T7674](https://phabricator.freedesktop.org/T7674)
+titled "Traceback when selecting a JPG file in the import dialog", the
+branch could be called T7674-import-img:
+
+```
+$ git checkout -b T7674-import-img origin/master
+```
+
+
+### Commit your changes
+
+Once you have made your changes, commit them in your local git
+repository. Follow the [GNOME
+guidelines](https://wiki.gnome.org/Newcomers/CodeContributionWorkflow#Commit_guidelines)
+for creating commits.
+
+Be aware that when you create a commit, `pre-commit` is executed to
+perform checks on the changes. In some cases it does some automatic
+fixes – when this happens, make sure those are included in the commit you
+want to create.
+
+
+### Upload your commit to Phabricator
+
+Now you're all set to push your first diff to
+[Phabricator](https://phabricator.freedesktop.org/tag/pitivi) for review!
+
+```
+(ptv-flatpak) $ git-phab attach
+```
+
+If there is no tracking information for the current branch,
+[git-phab](https://phabricator.freedesktop.org/diffusion/GITPHAB/repository/master/)
+will complain, as it won't be able to figure out what your changes are.
+You can specify the tracked branch like this:
+
+```
+$ git branch --set-upstream-to=origin/master
+```
+
+Attaching does many things:
+
+- Creates multiple Differential Revisions representing each of your
+unattached commits and updates the ones already attached. See for
+example [D1617](https://phabricator.freedesktop.org/D1617).
+
+- Amends the message of the previously-unattached commits so they
+contain the associated Differential Revision URL. See for example
+[b6a1384dbeef](https://phabricator.freedesktop.org/rPTVb6a1384dbeefe228158ad5aaf96fb53f6a7fffa9).
+
+- Finds out the Task ID from the branch name.
+
+- Attaches the Differential Revisions to the Task.
+
+- Pushes your branch to a "staging" git repo, so we can try exactly what
+you did.
+
+We'll get an automatic email and then review it ASAP.
+
+For those of you familiar with Phabricator's tool for managing
+revisions, pay attention `arc` creates a single revision for the entire
+branch, while our `git-phab` attaches each commit in the branch as a
+separate revision.
+
+
+## Using a custom staging repository
+
+Optionally, you can set git-phab to push your branches to a personal
+remote repository when you attach:
+
+1. Add your cloned remote Pitivi repository as a remote to your local repository:
+
+ ```
+ $ git remote add github https://github.com/NICK/pitivi.git
+ $ git remote set-url github https://github.com/NICK/pitivi.git
+ $ git remote set-url --push github git github com:NICK/pitivi.git
+ $ git remote show github | grep URL
+ Fetch URL: https://github.com/NICK/pitivi.git
+ Push URL: git github com:NICK/pitivi.git
+ ```
+2. Set git-phab remote to your cloned remote Pitivi repository:
+
+ ```
+ $ git config phab.remote github
+ ```
diff --git a/docs/Git.md b/docs/Git.md
index eac90d9..c5d8d59 100644
--- a/docs/Git.md
+++ b/docs/Git.md
@@ -1,246 +1,62 @@
-# Git
+---
+short-description: Specifics of using Git in Pitivi
+...
+
+# Using Git in Pitivi
[Git](http://git-scm.com) is the most popular [distributed revision
control
-system](http://en.wikipedia.org/wiki/Distributed_revision_control) used
-by the kernel, X, GStreamer, GNOME, etc... Git allows you to get a
-checkout (with full history) of the Pitivi code, create your own
-branches, publish those, etc... without the need for access to the
-central repository.
-
-Indeed, one of the very big strengths of a decentralized (a.k.a.
-distributed) system is that it is truly open and meritocratic: it allows
-you to do whatever changes you want to your repository, request
-feedback/reviews and then request that others pull your changes into the
-main repository on which others base their work upon. See
-<http://youtube.com/watch?v=4XpnKHJAok8#t=18m05s> for an explanation of
-this phenomenon.
-
-This page is not meant to be a general tutorial for Git; for that, see
-the [GNOME Git page](https://live.gnome.org/Git), the [official Git
-tutorial/documentation page](http://git-scm.com/documentation) and [git
-ready](http://gitready.com). In this page, we will cover some more
-advanced usage and the **specifics of how we use Git in the Pitivi
-project**. This is aimed at people coming from Bazaar or Subversion.
-
-# First steps: checking out the main repository
-
-`git clone `[`git://git.gnome.org/pitivi`](git://git.gnome.org/pitivi)` # do the initial repository
checkout`
-
-You should now have a directory called pitivi with the latest version of
-the files checked out. You are in the **`master`** branch.
-
-**Note**: unlike in Bazaar or other DVCSes, in git you only do this
-once; the “remotes” and branches in are all self-contained in the
-repository. In other words, you only do one checkout and do everything
-inside it using branches and remotes.
-
-# Dealing with remotes and branches
-
-You can see all local branches by using the `git branch` command. The
-branch you are working in is marked with an asterisk (**\***). You can
-view all branches, including the remote ones, by doing:
-
-`git branch -a`
-
-You'll notice that it shows you all the branches available from the
-<http://git.gnome.org/pitivi> repository.
-
-Let's say we add multiple people's remote repositories inside your local
-repository (see [Git repositories](Git_repositories.md) for the
-list of our known remotes):
-
-`git remote add nekohayo `[`https://github.com/nekohayo/pitivi.git`](https://github.com/nekohayo/pitivi.git)\
-`git remote add thiblahute
`[`https://github.com/thiblahute/pitivi.git`](https://github.com/thiblahute/pitivi.git)
-
-To update the remotes:
-
-`git remote update`
-
-And now you would be able to do stuff like:
-
-`git checkout thiblahute/somebranch`
-
-Or, to create a new local branch based on that branch:
-
-`git checkout -b mynewbranch thiblahute/somebranch`
-
-“git remote update” does not update your local branches, only the
-remotes. For example, if you have a local branch called “titles” based
-on “nekohayo/titles” (remote branch) and the “titles” branch on the
-“nekohayo” remote changed, you will have to checkout your local “titles”
-branch and update it to reflect the changes (with git pull --rebase, or
-a git reset --hard, depending on whether or not you want to keep your
-local changes).
-
-When the remote party has deleted some branches, you're still left with
-local copies of those remote branches... eventually you can clean it up
-with:
+system](http://en.wikipedia.org/wiki/Distributed_revision_control). Git
+allows you to get a checkout (with full history) of the Pitivi code, as
+a local git repository, and push your changes to a remote repository of
+your own, to make them available for others.
-`git remote prune REMOTE_NAME`
-
-I like to think of “git checkout” like “svn switch”: it allows you to
-move between branches (among other things). So, to go back to the main
-branch, you do “git checkout master”.
-
-## Creating a work branch
-
-It is good practice never to do work on the master branch (more details
-in the next section). Therefore you need to create a work branch :
-
-` git branch work master`
-
-If you use `git branch` you will now see your new branch... but you are
-still in `master`.
-
-To switch to your `work` branch you need to check it out using:
-
-` git checkout work`
-
-And it tells you it has successfully switched to the work branch.
-
-**Tip**: you can branch and checkout in one step using the
-`-b `<new_branch> option of `git checkout` Therefore the two steps above
-become:
-
-` git checkout -b work master`
-
-## Pitivi-specific gotcha: don't use git pull
-
-Typically, in Pitivi we use rebase and reset more often than “git merge”
-when merging your changes. This means two things:
-
-- You should not do your work directly on your “master” branch. You
- should do it in separate branches instead, unless you really know
- what you're doing and can handle resolving conflicts. We recommend
- that you keep master (or whatever the main development base is)
- identical to the upstream (“origin”) remote branch.
-- To update your local master branch (or whatever your base is) when
- you're on the local branch, always use “git pull --rebase”.
-
-Really, in the Pitivi context you don't want to use “git pull” (this
-creates merge commits and becomes quite messy over time). However, the
-general rules of thumb regarding rebasing are:
-
-- Branches on the official repository (git.gnome.org/pitivi) should
- only be fast-forward, because that's what contributors may base
- themselves upon
-- Individual contributors might use “git rebase -i” when they feel it
- necessary to sync up their work. Otherwise, we will do it at the
- time of the “merge” (so to speak). Rebasing is a more advanced
- notion, so refer to git ready and to this Pitivi-specific video
- tutorial: <http://youtube.com/watch?v=6WU4jKti_vo>
-
-# Publishing your work / adding your own remote to push to
+In this page, we cover **specifics of how we use Git in the Pitivi
+project**. For an introduction to Git, see the [official Git
+tutorial/documentation page](http://git-scm.com/documentation) and [git
+ready](http://gitready.com).
-Several free git hosting services exist out there where you can create
-very quickly some repositories and publish your branch there. These
-websites will contain information on how to add your publishing remote
-URL. Here's an example of how you can add your remote git repository
-where you'll push your changes, with github (notice that I named the
-remote “github” instead of “origin”, since origin is git.gnome.org):
-`git remote add github git github com:my_user/pitivi.git`
+## Sending changes around
-Let's say you created a working branch locally (called `mytest`) and
-that you named your remote repository `myremote`, and you want to
-publish it so people can see what you have done, try it out, etc. The
-first time you will have to tell git **where** you want to push that
-branch:
+As can be seen in the [development workflow](Development_workflow.md),
+we normally don't take care of pushing branches around, as this is done
+automatically by git-phab. Once somebody attaches a branch to a task
+with git-phab, all of us can try it with:
-` git push myremote mytest`
+```
+git-phab fetch T1234 -c
+```
-This will automatically:
-- Create a `mytest` branch on your remote repository
-- Copy over all the commits
-- Make git remember where that branch is stored remotely
+## When to use git pull
-The next time you want to push your work remotely, you just to be within
-that branch and do:
+With rare exceptions, in Pitivi we rebase contributed commits before
+pushing them to origin/master, to avoid merge commits. This worked fine
+and it enforces some discipline, so there is no plan to change it. It's
+similar with Phabricator's philosophy (`arc land` squashes all the
+commits in the current branch into a single one before pushing to
+origin/master) — just that we like to keep control.
-` git push`
+When working on a task, assuming you're following the [development
+workflow](Development_workflow.md), you should have a specific branch.
+To get the latest changes in your branch, normally in Pitivi you should
+do something like `git fetch` and `git rebase origin/master`.
-To delete a branch (or tag) on the remote repository:
+It should be safe to use `git pull` on the master branch if you don't
+work on it. Just make sure it's exactly what origin/master is and no
+merge commit is created.
-`git push REMOTENAME :BRANCHNAME`
-This command may look strange, but it is literally telling git *push,
-onto REMOTENAME, “nothing” into BRANCHNAME*.
+## Not going insane
-Once that's done, others will be able to do a “git remote prune” to see
-those changes on their end.
+It's much easier to understand what's the status of a git branch by
+using a graphical tool such as `gitk` or
+[gitg](https://wiki.gnome.org/Apps/Gitg) (tailored for GNOME, with a
+really nice interface).
-# Not going insane
+[Meld](http://meldmerge.org) can be very useful for reviewing a large
+change to be committed.
-You are very quickly going to have a lot of branches. There are
-graphical tools to view what you have locally and make some
-changes/actions without needing to rely on the command line (unless you
-prefer the command line interface). We recommend
-[gitg](https://wiki.gnome.org/Apps/Gitg) (tailored for GNOME, with a
-really nice interface), though there are others like giggle or gitk.
-
-Other *very* useful tools are:
-
-- [Git Meld](https://github.com/wmanley/git-meld) (not needed anymore,
- simply put “meld = difftool --dir-diff -t meld” in the alias section
- of your \~/.gitconfig file)
-- [Showing the current branch name at all
- times](http://asemanfar.com/Current-Git-Branch-in-Bash-Prompt)
-- [Git autocompletion for
- Bash](http://gitready.com/advanced/2009/02/05/bash-auto-completion.html)
-
-Nice Git features to learn about:
-
-- “git grep”
-- “git bisect” (for pinpointing regressions)
-- “git rebase -i” is an extremely powerful tool once you get used to
- it. See the various tutorials/documentation about it, this
- Pitivi-specific video tutorial:
- <http://youtube.com/watch?v=6WU4jKti_vo>
-- “git add -p” (or use the little “+” icons in
- [gitg](https://wiki.gnome.org/Apps/Gitg)'s commit mode) to
- stage/commit only portions of a file (allowing you to easily plan
- and split work across different commits)
-
-## Tips and tricks/gotchas for Bazaar/Subversion users
-
-- To revert some files to the version provided by git, use “git
- checkout thefiles”, not “git revert”.
-- “git checkout” is also used for switching between branches (or to
- any particular commit/point in the history). It is somewhat similar
- to “svn switch”.
-- To create a branch, you do “git checkout -b my\_new\_local\_branch
- theremote/thesourcebranch”, not “git branch”.
-- To delete a branch, you do “git branch -D thebranch”.
-- To apply a patch without committing, use “git apply foo.diff”
-- To apply a patch and create commits at the same time, use “git am
- foo.patch”
-- In the Pitivi context, do not ever use “git pull” (unless you really
- know what you're doing). Use “git pull --rebase”, to get the
- equivalent of a “svn up”. If you have changes in the branch you're
- “pulling”, it will rebase them on top of it (but, as mentioned
- previously, you should not do your work directly on the master
- branch unless you know what you're doing and know how to resolve
- potential rebase conflicts).
-
-Git's syntax can arguably be quite arcane. Take a look at the
-\~/.gitconfig file: you can add an \[alias\] section to create command
-aliases. This is nekohayo's gitconfig:
-
-`[alias]`\
-` diffstat = diff --stat`\
-` staged = diff --cached`\
-` unstaged = diff`\
-` both = diff HEAD`\
-` oneline = log --pretty=oneline --abbrev-commit`
-
-` newbranch = checkout -b # destination source, not the other way around`\
-` deletebranch = branch -D`\
-` switch = checkout`\
-` uncommit = reset HEAD~1`\
-` nukefromorbit = clean -fxd # use with extreme caution.`\
-` up = pull --rebase`\
-` patch = am`
-
-` meld = difftool --dir-diff -t meld`
+Set up your prompt to show the current branch info, and make sure
+tab-completion works.
diff --git a/docs/HACKING.md b/docs/HACKING.md
index 42d90da..1c9f2f0 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -1,25 +1,43 @@
-# Hacking on Pitivi
+---
+short-description: Using the Pitivi development environment
+...
-## The Pitivi development environment
+# Hacking on Pitivi
The official way of getting your environment up and running is by using
[flatpak](http://flatpak.org/). For this you need to
[install flatpak](http://flatpak.org/getting.html) on your system,
-along with flatpak-builder, which might be provided by an
-additional package on some distributions (please tell us if it is the case
-for yours so we can make a list here).
+along with flatpak-builder. Note flatpak-builder might be provided by an
+additional package on some distributions (such as Archlinux).
-### Setting up the development environment
+## Setting up the development environment
Create a development environment folder and get the [Pitivi source
code](https://git.gnome.org/browse/pitivi/tree/) into it:
+
```
$ mkdir pitivi-dev
$ cd pitivi-dev
$ git clone https://git.gnome.org/browse/pitivi
```
-When you hack on Pitivi, enter the development environment to get:
+Whenever you want to hack on Pitivi, enter the development environment:
+```
+$ cd pitivi-dev/pitivi && source bin/pitivi-env
+-> Setting up the prefix for the sandbox...
+Using Pitivi prefix in /.../pitivi-dev/pitivi-prefix
+[prefix being built, if not already...]
+Running in sandbox: echo Prefix ready
+Prefix ready
+```
+
+This can take a while when creating the sandbox from scratch. Note the
+prompt changes:
+```
+(ptv-flatpak) $
+```
+
+By entering the development environment, you get:
- a [Flatpak sandbox](http://docs.flatpak.org/en/latest/working-with-the-sandbox.html)
for the dependencies, in `pitivi-dev/pitivi-prefix`
- a [Python virtual environment](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
@@ -30,17 +48,9 @@ in `pitivi-dev/pitivi/build/flatpak/pyvenv`
- the [Meson build directory](http://mesonbuild.com/Quick-guide.html),
in `pitivi-dev/pitivi/mesonbuild`
- some aliases for the build tools, such as `ninja`, so they are executed in the sandbox.
-```
-$ cd pitivi-dev/pitivi && source bin/pitivi-env
--> Setting up the prefix for the sandbox...
-Using Pitivi prefix in /.../pitivi-dev/pitivi-prefix
-[prefix being built, if not already...]
-Running in sandbox: echo Prefix ready
-Prefix ready
-```
-Note: This can take a while when creating the sandbox from scratch.
-Run the [unittests](Testing.md):
+Now that you are in the development environment, try running the
+[unittests](Testing.md):
```
(ptv-flatpak) $ ninja -C mesonbuild/ test
Running in sandbox: ninja -C mesonbuild/ test
@@ -52,51 +62,20 @@ Hack away, and check the effect of you changes by simply running:
```
-### Development Workflow
-
-We use [Phabricator tasks](https://phabricator.freedesktop.org/tag/pitivi/) to track all bugs and feature
requests; feel free to open a task if you have found a bug or
-wish to see a feature implemented if it doesn't exist already.
-You can even subscribe to tasks on Phabricator to keep yourself updated with their progress.
-If you're a newcomer wanting to contribute, you can start with tasks tagged [Pitivi tasks for
newcomers](https://phabricator.freedesktop.org/tag/pitivi_tasks_for_newcomers/) to get involved.
-
-To fix a task, it's best to get in touch with us on our IRC channel `#pitivi` on Freenode, to see if it's
still meaningful, then if all is well:
-
-1. Assign the task to yourself in Phabricator.
-2. Create a new branch with a relevant name. Make sure to set its [remote-tracking
branch](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches/), as it determines the default commit
range to attach.
-For example, if you're going to work on task [T7674](https://phabricator.freedesktop.org/T7674/), the branch
could be called T7674-import-img or
-T7674-fix-import, i.e. `git checkout -b T7674-import-img origin/master`.
-3. Once you have made your changes, you need to create a commit. Follow the [GNOME
guidelines](https://wiki.gnome.org/Newcomers/CodeContributionWorkflow#Commit_guidelines)
-for creating commits.
-
- Be aware that when you create a commit, `pre-commit` is executed to perform checks on the changes and in
some cases it does
-some automatic fixes. When this happens, make sure those are included in the commit you want to create.
-4. Now you're all set to push your first diff to
-[Phabricator](https://phabricator.freedesktop.org/tag/pitivi) for review!
-
- ```
- (ptv-flatpak) $ git-phab attach --task TXXXX
- ```
-
-Optionally, you can set git-phab to automatically push your WIP branches to a personal remote repository:
-
-1. Add your cloned remote Pitivi repository as a remote to your local repository:
+### Updating the development environment
- ```
- $ git remote add github https://github.com/NICK/pitivi.git
- $ git remote set-url github https://github.com/NICK/pitivi.git
- $ git remote set-url --push github git github com:NICK/pitivi.git
- $ git remote show github | grep URL
- Fetch URL: https://github.com/NICK/pitivi.git
- Push URL: git github com:NICK/pitivi.git
- ```
-2. Set git-phab remote to your cloned remote Pitivi repository:
+To update the dependencies installed in the sandbox, run:
+```
+(ptv-flatpak) $ ptvenv --update
+```
- ```
- $ git config phab.remote github
- ```
+That will actually recreate the sandbox prefix, updating all
+dependencies from their git repos and tarballs as defined in the
+[flatpak
+manifest](https://git.gnome.org/browse/pitivi/tree/build/flatpak/pitivi.template.json) (located at
`build/flatpak/pitivi.template.json`).
-### Building the C parts
+### Building the Pitivi C parts
Select parts of Pitivi are written in C and need to be built when changed,
such as the audio envelope renderer for the audio clips. Build them with:
@@ -106,19 +85,7 @@ Running in sandbox: ninja -C mesonbuild/
```
-### Updating the development environment
-
-To update the dependencies installed in the sandbox, run:
-```
-(ptv-flatpak) $ ptvenv --update
-```
-
-That will actually recreate the prefix, update all dependencies from their
-git repos and tarballs as defined in the [flatpak
manifest](https://git.gnome.org/browse/pitivi/tree/build/flatpak/pitivi.template.json) (located
-at build/flatpak/pitivi.template.json)
-
-
-### Working on Pitivi dependencies (Meson)
+### Hacking on Pitivi dependencies (Meson)
If you have to work on say, [GStreamer Editing
Services](https://gstreamer.freedesktop.org/modules/gst-editing-services.html)
which is built using the Meson build system, first clone it into your
@@ -153,7 +120,7 @@ Also beware that it will not take into account not committed
changes.
-### Working on Pitivi dependencies (Autotools, Make, etc)
+### Hacking on Pitivi dependencies (Autotools, Make, etc)
If the project you are working on is built with other tools, make sure
they are run in the sandbox by using `ptvenv`. For example:
@@ -169,94 +136,13 @@ Running in sandbox: make
```
-## Coding Style Guide
-
-We rely on the [Python Style Guide PEP-8](https://www.python.org/dev/peps/pep-0008/)
-
-The only exception to it is regarding the "80 columns" rule.
-Since Python is a very concise/compact language, we can afford to be
-a little bit more flexible on the line length than languages such as C.
-
-When deciding whether or not you should split your line when it exceeds
-79 characters, ask yourself: "Does it truly improve legibility?"
-
-What this translates to is:
-
-- Avoid having very long lines.
-
-- When the contents only slightly exceeds the 80 chars limit,
-consider keeping it on one line. Otherwise it just hurts legibility and
-gives a weird "shape" to the code.
-
-### Names
-The function names, method names and other class attributes should be
-small_caps_with_underscore. For example:
-``` python
-def some_function():
- return ""
-
-class MyClass:
-
- def a_really_important_method(self):
- self.do_something()
-
- @property
- def water_level(self):
- """The level of the water in meters."""
- return self.__water_level
-```
-
-To illustrate how private a method or other class field is, prepend
-one or two underscores:
-``` python
- class MyClass:
-
- def public_method(self):
- ...
-
- def _protected_method(self):
- ...
-
- def __private_method(self):
- ...
-```
-
-Unused arguments in methods should be prefixed with `unused_`.
-The most common place where this would happen is in callbacks from
-gobject signals. For example, below we don't use the second argument,
-but we do use `pad`.
-
-``` python
- def __pad_added_cb(self, unused_element, pad):
- self.do_something_with(pad)
-```
-
-The name of a callback method should:
-
- - be prepended with two underscores since it's private
- - be appended with `cb`
-
-``` python
- class MyClass:
-
- def some_method(self):
- self.someobject.connect('event', self.__some_object_event_cb)
-
- def __some_object_event_cb(self, object, arg):
- print "our callback was called"
-```
-
-### Imports order
-You can guess the order of the imported modules by looking at some py files.
-The pre-commit hook has authority in this case as it will reorder the imports
-if the order is not good.
-
## Profiling Pitivi
-To profile a pitivi run, simply set the PITIVI_PROFILING environment variable to 1, like so:
+To profile a Pitivi run, simply set the `PITIVI_PROFILING` environment
+variable to 1, like so:
```
-$ PITIVI_PROFILING=1 pitivi
+(ptv-flatpak) $ PITIVI_PROFILING=1 pitivi
```
A file named `pitivi-runstats` will be created in the current directory, a handy tool to examine it is
`gprof2dot.py`, install it with:
diff --git a/docs/Pitivi_Love.md b/docs/Pitivi_Love.md
index d88cf3c..e39dbdf 100644
--- a/docs/Pitivi_Love.md
+++ b/docs/Pitivi_Love.md
@@ -1,6 +1,10 @@
+---
+short-description: Things beginners can help us with
+...
+
# Pitivi Love
-See the [Pitivi tasks for
-newcomers](https://phabricator.freedesktop.org/project/view/111/) which
-lists small bugs and features you could jump right away and also larger
+The [Pitivi tasks for
+newcomers](https://phabricator.freedesktop.org/project/view/111/)
+lists small bugs and features you could jump on right away and also larger
cool features to implement.
diff --git a/docs/Testing.md b/docs/Testing.md
index 1afd3a3..f1b3a52 100644
--- a/docs/Testing.md
+++ b/docs/Testing.md
@@ -14,15 +14,21 @@ you want to test more thoroughly.
You can run the unit tests with:
-`ninja -C mesonbuild/ test`
+```
+ninja -C mesonbuild/ test
+```
If you want to run only one particular unit test, use:
-`gst-validate-launcher tests/ptv_testsuite.py -t
tests.test_project.TestProjectManager.testLoadProjectFailedUnknownFormat`
+```
+gst-validate-launcher tests/ptv_testsuite.py -t
tests.test_project.TestProjectManager.testLoadProjectFailedUnknownFormat
+```
Listing tests:
-`gst-validate-launcher tests/ptv_testsuite.py -L`
+```
+gst-validate-launcher tests/ptv_testsuite.py -L
+```
### Writing unit tests
@@ -59,8 +65,6 @@ each time Pitivi is used.
You can run the integration tests with:
-`tests/validate-tests/runtests`
-
-See also:
-
-- [Test suite wishlist](Test_suite_wishlist.md)
+```
+tests/validate-tests/runtests
+```
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index bf8c8da..deafcf9 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -2,8 +2,9 @@ index.md
Install_with_flatpak.md
Bug_reporting.md
HACKING.md
+ Development_workflow.md
Git.md
- Git_repositories.md
+ Coding_style_guide.md
Command_line_tools.md
Pitivi_Love.md
The_people.md
@@ -50,7 +51,6 @@ index.md
Feroze_gsoc.md
Testing.md
QA_Scenarios.md
- Test_suite_wishlist.md
design.md
design/Why_python.md
design/Proxy_editing_requirements.md
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
