quick-docs/en-US/anaconda/anaconda_contribute.adoc

= Contributing to Anaconda and related projects

This wiki page aims to explain how and where to most effectively contribute to the Anaconda installer and related projects.

== Not just Anaconda - choosing where to contribute

The Anaconda installer used to be quite monolithic, but this is no longer the case, and there is a growing trend to split parts of Anaconda to separate modules and libraries.
This not only helps to improve modularity, but also makes it possible to use these libraries outside of the Anaconda installer.

Before contributing to Anaconda or one of its components, it is often necessary to find out which library or component the feature in question is implemented.

What follows is a brief description of the various project under the Anaconda umbrella.

=== anaconda

The Fedora/RHEL installer itself.
All installation-specific code--the GUI, TUI and a lot of glue code--for using the various Anaconda related modules and libraries belongs to the Anaconda project.

link:https://github.com/rhinstaller/anaconda[https://github.com/rhinstaller/anaconda]

=== pykickstart

A python library for manpulating kickstart files.
It contains a data representation of kickstart files, a parser to read the data representation, and a writer to generate kickstart files.

link:https://github.com/rhinstaller/pykickstart[https://github.com/rhinstaller/pykickstart]

=== initial setup

An application that can run during the first start of a newly installed computer and makes it possible to configure the computer according to the needs of the user.

link:https://github.com/rhinstaller/initial-setup[https://github.com/rhinstaller/initial-setup]

=== python-meh

A python library for handling, saving, and reporting exceptions.

link:https://github.com/rhinstaller/python-meh[https://github.com/rhinstaller/python-meh]

=== But that's not all!

This is not an exhaustive listing - there are many other sub-projects under the Anaconda umbrella and the best way to check them out is to visit the link:https://github.com/rhinstaller[Red Hat Installer Engineering Team organization on GitHub].

== Contributing code

Anaconda and all related projects are open source software and are looking forward to sensible contributions to their source code.

Please view our link:anaconda_release_process.html[patch review guidelines] for detailed information on the process and policies concerning patch submission.
This can be summarized as:

* Patches can be submitted either by email or as a pull request on Github
* All patches are reviewed by other contributors
* If a patch has been accepted, it will be pushed to the repository by a contributor who has commit access

== Filing bugs and feature requests
As Anaconda is a Linux distribution installer you should usually fill bugs and feature requests in the bugtracker of the given distribution.
For example:
* https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora for Fedora Anaconda bugs/RFEs use the Fedora product on bugzilla.redhat.com
* https://bugzilla.redhat.com/enter_bug.cgi?classification=Red%20Hat for RHEL Anaconda bugs/RFEs use the Red Hat component on bugzilla.redhat.com

For generic upstream Anaconda issues you can use the the Anaconda GitHub issue tracker.


The same applies to other Anaconda-related projects - use the distribution bug tracker for the distribution related bugs/RFEs and the GitHub tracker for generic upstream issues.

== Helping with Anaconda testing

Contributions to anaconda or any projects which fall under the installer umbrella are always welcome.
If you are interested in helping out, testing your changes before submitting patches is highly recommended.
There are different ways to test changes--the following is only one, relatively simple way.

=== Pre-requisites

* Anaconda source tree, which can be obtained: https://github.com/rhinstaller/anaconda
* You can test on bare metal, but this guide assumes testing on a VM using qemu.
* Web space: Having some publicly available web space is helpful for posting updates.img and link:http://pykickstart.readthedocs.io/en/latest/[kickstart] files.
These are helpful both for your development and for distributing to other people for testing.
* HTTP/FTP server: For testing remote install methods, you'll need a server running that has the correct trees available.
These methods are not tested all that often, so this isn't typically all that important.
Close to a release, you will want to have access to this however.
* Virtualization: qemu is used here, so grab `qemu-kvm, qemu-kvm-tools, qemu-system-x86` and `qemu-img`

=== Local branches and creating an updates.img
* By default, you are on master branch.
This is "upstream", aka rawhide.
Various versions of Fedora follow the form `f$releasever-branch`.

* Note that while you can test out any changes you wish, you will not be able to push them to any of the remote branches unless you are an approved contributor.
If you have patches you'd like to see integrated into the code base, please link:anaconda_review_process.html[send a patch or create a pull request in GitHub].

* An easy way to test changes is to create a new, local branch based off of a version of anaconda -- usually the most recently built version, or a last known "good" release.
Checkout the release tag, and then create a new branch from this.

----
git checkout anaconda-22.15-1
git checkout -b newbranch
----

* Make any necessary changes, and commit them.

----
git add $files
git commit -m "Some message"
----

* To test your changes, create an updates.img, which you can load at boot time.
See the [[Anaconda/Updates|Anaconda Updates wiki page]] for more information about Anaconda updates.img creation and usage.

----
./scripts/makeupdates
----

* Upload the updates.img to some web space.

=== Testing out changes
* Grab the latest build of Fedora (the anaconda version your updates.img is built against *MUST* match the the version of anaconda in the Fedora compose you are testing).
If you want to use an older image, link:anaconda_updates.html[you can use use the -t flag for the makeupdates script].
* Prepare some empty disk images.
----
 qemu-img create test.img 8G
----
* Boot the ISO (Note: this allocates 1024MB of RAM.
Adjust accordingly based on your resource availability)
----
 qemu-kvm -hda test.img -cdrom ~/isos/boot.iso -boot d -m 1024
----
* At the splash screen, hit TAB over the "Install Fedora...." entry.
This exposes the command line that will be used for booting, where you can add the boot parameter to load your updates.img.
----
inst.updates=http://path.to/updates.img
----

== Improving the Anaconda documentation

== Translations and localization
Anaconda is being translated on the link:https://zanata.org[Zanata] translation platform.

If you want to help Translate Anaconda, just register on the link:https://fedora.zanata.org/[Fedora Zanata instance], switch to the link:https://fedora.zanata.org/project/view/anaconda[Anaconda project] and start translating! :-)

= How builds and packages are made

Builds are done in a periodic manner or if there is no pressing need for a build once enough changes accumulate.
There is always one Anaconda contributor who is "in charge" of doing builds for a given Anaconda release branch (rawhide/master, f<number>-branch, rhel<number>-branch, etc.).
One person can be "in charge" of a single or multiple release branches.
If you have a question for the person doing builds for a given branch, the best way is to ask on our IRC channel who is handling builds for the branch and ask him/her.

Creating a build amounts to bumping the version, adding a new changelog version (changelog is usually based on commit message headers from commits added since the last release) and attaching a tag to this commit.

Next comes source tarball creation (this includes pulling in new translation updates), followed by srpm creation with the rpmbuild tool.
The srpm is then imported to the Fedora distgit with the fedpkg tool a new build triggered in Koji.

In the rawhide branch all the builds go directly to the repositories, but in stable/soon to be stable Fedora releases they need to pass the Bodhi community QA process first.

= Contact

=== IRC

The link:https://duck.co/redir/?u=http%3A%2F%2Fwebchat.freenode.net%2F%3Fchannels%3Danaconda[#anaconda] channel on Freenode is available for general discussion about the Anaconda installer and related projects.

=== Mailing Lists

link:mailto:anaconda-devel-list@redhat.com[anaconda-devel-list@redhat.com] (link:https://www.redhat.com/archives/anaconda-devel-list/[archive]) - general discussion about the development of the Anaconda installer and related project

link:mailto:anaconda-patches@lists.fedorahosted.org[anaconda-patches@lists.fedorahosted.org] (link:https://lists.fedorahosted.org/pipermail/anaconda-patches/[archive]) - patch review for Anaconda and related projects

link:mailto:kickstart-list@redhat.com[kickstart-list@redhat.com] (link:https://www.redhat.com/archives/kickstart-list/[archive]) - discussion about the link:https://github.com/rhinstaller/pykickstart[kickstart]] format
Add the "Contribution" page 2018-02-27 11:02:19 +00:00			`= Contributing to Anaconda and related projects`

			`This wiki page aims to explain how and where to most effectively contribute to the Anaconda installer and related projects.`

			`== Not just Anaconda - choosing where to contribute`

			`The Anaconda installer used to be quite monolithic, but this is no longer the case, and there is a growing trend to split parts of Anaconda to separate modules and libraries.`
			`This not only helps to improve modularity, but also makes it possible to use these libraries outside of the Anaconda installer.`

			`Before contributing to Anaconda or one of its components, it is often necessary to find out which library or component the feature in question is implemented.`

			`What follows is a brief description of the various project under the Anaconda umbrella.`

			`=== anaconda`

			`The Fedora/RHEL installer itself.`
			`All installation-specific code--the GUI, TUI and a lot of glue code--for using the various Anaconda related modules and libraries belongs to the Anaconda project.`

			`link:https://github.com/rhinstaller/anaconda[https://github.com/rhinstaller/anaconda]`

			`=== pykickstart`

			`A python library for manpulating kickstart files.`
			`It contains a data representation of kickstart files, a parser to read the data representation, and a writer to generate kickstart files.`

			`link:https://github.com/rhinstaller/pykickstart[https://github.com/rhinstaller/pykickstart]`

			`=== initial setup`

			`An application that can run during the first start of a newly installed computer and makes it possible to configure the computer according to the needs of the user.`

			`link:https://github.com/rhinstaller/initial-setup[https://github.com/rhinstaller/initial-setup]`

			`=== python-meh`

			`A python library for handling, saving, and reporting exceptions.`

			`link:https://github.com/rhinstaller/python-meh[https://github.com/rhinstaller/python-meh]`

			`=== But that's not all!`

			`This is not an exhaustive listing - there are many other sub-projects under the Anaconda umbrella and the best way to check them out is to visit the link:https://github.com/rhinstaller[Red Hat Installer Engineering Team organization on GitHub].`

			`== Contributing code`

			`Anaconda and all related projects are open source software and are looking forward to sensible contributions to their source code.`

			`Please view our link:anaconda_release_process.html[patch review guidelines] for detailed information on the process and policies concerning patch submission.`
			`This can be summarized as:`

			`* Patches can be submitted either by email or as a pull request on Github`
			`* All patches are reviewed by other contributors`
			`* If a patch has been accepted, it will be pushed to the repository by a contributor who has commit access`

			`== Filing bugs and feature requests`
			`As Anaconda is a Linux distribution installer you should usually fill bugs and feature requests in the bugtracker of the given distribution.`
			`For example:`
			`* https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora for Fedora Anaconda bugs/RFEs use the Fedora product on bugzilla.redhat.com`
			`* https://bugzilla.redhat.com/enter_bug.cgi?classification=Red%20Hat for RHEL Anaconda bugs/RFEs use the Red Hat component on bugzilla.redhat.com`

			`For generic upstream Anaconda issues you can use the the Anaconda GitHub issue tracker.`


			`The same applies to other Anaconda-related projects - use the distribution bug tracker for the distribution related bugs/RFEs and the GitHub tracker for generic upstream issues.`

			`== Helping with Anaconda testing`

			`Contributions to anaconda or any projects which fall under the installer umbrella are always welcome.`
			`If you are interested in helping out, testing your changes before submitting patches is highly recommended.`
			`There are different ways to test changes--the following is only one, relatively simple way.`

			`=== Pre-requisites`

			`* Anaconda source tree, which can be obtained: https://github.com/rhinstaller/anaconda`
			`* You can test on bare metal, but this guide assumes testing on a VM using qemu.`
			`* Web space: Having some publicly available web space is helpful for posting updates.img and link:http://pykickstart.readthedocs.io/en/latest/[kickstart] files.`
			`These are helpful both for your development and for distributing to other people for testing.`
			`* HTTP/FTP server: For testing remote install methods, you'll need a server running that has the correct trees available.`
			`These methods are not tested all that often, so this isn't typically all that important.`
			`Close to a release, you will want to have access to this however.`
			* Virtualization: qemu is used here, so grab `qemu-kvm, qemu-kvm-tools, qemu-system-x86` and `qemu-img`

			`=== Local branches and creating an updates.img`
			`* By default, you are on master branch.`
			`This is "upstream", aka rawhide.`
			Various versions of Fedora follow the form `f$releasever-branch`.

			`* Note that while you can test out any changes you wish, you will not be able to push them to any of the remote branches unless you are an approved contributor.`
			`If you have patches you'd like to see integrated into the code base, please link:anaconda_review_process.html[send a patch or create a pull request in GitHub].`

			`* An easy way to test changes is to create a new, local branch based off of a version of anaconda -- usually the most recently built version, or a last known "good" release.`
			`Checkout the release tag, and then create a new branch from this.`

			`----`
			`git checkout anaconda-22.15-1`
			`git checkout -b newbranch`
			`----`

			`* Make any necessary changes, and commit them.`

			`----`
			`git add $files`
			`git commit -m "Some message"`
			`----`

			`* To test your changes, create an updates.img, which you can load at boot time.`
			`See the [[Anaconda/Updates\|Anaconda Updates wiki page]] for more information about Anaconda updates.img creation and usage.`

			`----`
			`./scripts/makeupdates`
			`----`

			`* Upload the updates.img to some web space.`

			`=== Testing out changes`
			`* Grab the latest build of Fedora (the anaconda version your updates.img is built against MUST match the the version of anaconda in the Fedora compose you are testing).`
			`If you want to use an older image, link:anaconda_updates.html[you can use use the -t flag for the makeupdates script].`
			`* Prepare some empty disk images.`
			`----`
			`qemu-img create test.img 8G`
			`----`
			`* Boot the ISO (Note: this allocates 1024MB of RAM.`
			`Adjust accordingly based on your resource availability)`
			`----`
			`qemu-kvm -hda test.img -cdrom ~/isos/boot.iso -boot d -m 1024`
			`----`
			`* At the splash screen, hit TAB over the "Install Fedora...." entry.`
			`This exposes the command line that will be used for booting, where you can add the boot parameter to load your updates.img.`
			`----`
			`inst.updates=http://path.to/updates.img`
			`----`

			`== Improving the Anaconda documentation`

			`== Translations and localization`
			`Anaconda is being translated on the link:https://zanata.org[Zanata] translation platform.`

			`If you want to help Translate Anaconda, just register on the link:https://fedora.zanata.org/[Fedora Zanata instance], switch to the link:https://fedora.zanata.org/project/view/anaconda[Anaconda project] and start translating! :-)`

			`= How builds and packages are made`

			`Builds are done in a periodic manner or if there is no pressing need for a build once enough changes accumulate.`
			`There is always one Anaconda contributor who is "in charge" of doing builds for a given Anaconda release branch (rawhide/master, f<number>-branch, rhel<number>-branch, etc.).`
			`One person can be "in charge" of a single or multiple release branches.`
			`If you have a question for the person doing builds for a given branch, the best way is to ask on our IRC channel who is handling builds for the branch and ask him/her.`

			`Creating a build amounts to bumping the version, adding a new changelog version (changelog is usually based on commit message headers from commits added since the last release) and attaching a tag to this commit.`

			`Next comes source tarball creation (this includes pulling in new translation updates), followed by srpm creation with the rpmbuild tool.`
			`The srpm is then imported to the Fedora distgit with the fedpkg tool a new build triggered in Koji.`

			`In the rawhide branch all the builds go directly to the repositories, but in stable/soon to be stable Fedora releases they need to pass the Bodhi community QA process first.`

			`= Contact`

			`=== IRC`

			`The link:https://duck.co/redir/?u=http%3A%2F%2Fwebchat.freenode.net%2F%3Fchannels%3Danaconda[#anaconda] channel on Freenode is available for general discussion about the Anaconda installer and related projects.`

			`=== Mailing Lists`

			`link:mailto:anaconda-devel-list@redhat.com[anaconda-devel-list@redhat.com] (link:https://www.redhat.com/archives/anaconda-devel-list/[archive]) - general discussion about the development of the Anaconda installer and related project`

			`link:mailto:anaconda-patches@lists.fedorahosted.org[anaconda-patches@lists.fedorahosted.org] (link:https://lists.fedorahosted.org/pipermail/anaconda-patches/[archive]) - patch review for Anaconda and related projects`

			`link:mailto:kickstart-list@redhat.com[kickstart-list@redhat.com] (link:https://www.redhat.com/archives/kickstart-list/[archive]) - discussion about the link:https://github.com/rhinstaller/pykickstart[kickstart]] format`