Skip to content

Commit c88b73d

Browse files
lonnieezelllonnieezell
authored
Merge pull request #120 from jim-parry/docs/workflow
Rewrite workflow explanation
2 parents 824a94e + 8ae1245 commit c88b73d

3 files changed

Lines changed: 222 additions & 28 deletions

File tree

‎user_guide_src/source/contributing/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ Contributing to CodeIgniter
66
:titlesonly:
77

88
guidelines
9-
process
9+
workflow
10+
signing
1011
roadmap
1112
internals
1213
documentation

user_guide_src/source/contributing/process.rst renamed to user_guide_src/source/contributing/signing.rst

Lines changed: 18 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,9 @@
11
====================
2-
Contribution Process
2+
Contribution Signing
33
====================
44

5-
Branching
6-
=========
7-
8-
CodeIgniter uses the `Git-Flow
9-
<http://nvie.com/posts/a-successful-git-branching-model/>`_ branching model
10-
which requires all pull requests to be sent to the "develop" branch. This is
11-
where the next planned version will be developed. The "master" branch will
12-
always contain the latest stable version and is kept clean so a "hotfix" (e.g:
13-
an emergency security patch) can be applied to master to create a new version,
14-
without worrying about other features holding it up. For this reason all
15-
commits need to be made to "develop" and any sent to "master" will be closed
16-
automatically. If you have multiple changes to submit, please place all
17-
changes into their own branch on your fork.
18-
19-
One thing at a time: A pull request should only contain one change. That does
20-
not mean only one commit, but one change - however many commits it took. The
21-
reason for this is that if you change X and Y but send a pull request for both
22-
at the same time, we might really want X but disagree with Y, meaning we
23-
cannot merge the request. Using the Git-Flow branching model you can create
24-
new branches for both of these features and send two requests.
25-
26-
Why Signing Is Important
27-
=======================
28-
29-
We ask that contributions have code commits signed. This is important in order
30-
to prove, as best we can, the provenance of contributions.
5+
We ask that contributions have code commits signed. **This is important in order
6+
to prove, as best we can, the provenance of contributions.**
317

328
The developer pushing a commit as part of a PR isn't necessarily the person
339
who committed it originally, if the commit is not signed. This distorts the
@@ -116,3 +92,18 @@ The basic steps are
11692

11793
Depending on your IDE, you may have to do your Git commits from your Git bash shell
11894
to use the **-S** option to force the secure signing.
95+
96+
Commit Messages
97+
===============
98+
99+
Regardless of how you sign a commit, commit messages are important too.
100+
They communicate the intent of a specific change, concisely.
101+
They make it easier to review code, and to find out why a change was made
102+
if the code history is examined later.
103+
104+
The audience for your commit messages will be the codebase maintainers, any
105+
code reviewers, and debuggers trying to figure out when a bug might have been
106+
introduced.
107+
108+
Do try to make your commit messages meaningful.
109+
.

‎user_guide_src/source/contributing/workflow.rst‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
=====================
2+
Contribution Workflow
3+
=====================
4+
5+
Much of the workflow for contributing to CodeIgniter (or any project) involves
6+
understanding how `Git <https://git-scm.com/>`_ is used to
7+
manage a shared repository and contributions to it.
8+
Examples below use the Git bash shell, to be as platform neutral as
9+
possible. Your IDE may make some of these easier.
10+
11+
Some conventions used below, which you will need to provide appropriate
12+
values for when you try these::
13+
14+
ALL_PROJECTS // folder location with all your projects in subfolders, eg /lampp/htdocs
15+
YOUR_PROJECT // folder containing the project you are working on, inside ALL_PROJECTS
16+
ORIGIN_URL // the cloning URL for your repository fork
17+
UPSTREAM_URL // the cloning URL for the CodeIgniter4 repository
18+
19+
Branching
20+
=========
21+
22+
CodeIgniter uses the `Git-Flow
23+
<http://nvie.com/posts/a-successful-git-branching-model/>`_ branching model,
24+
which requires all pull requests to be sent to the "develop" branch. This is
25+
where the next planned version will be developed. The "master" branch will
26+
always contain the latest stable version and is kept clean so a "hotfix" (e.g:
27+
an emergency security patch) can be applied to master to create a new version,
28+
without worrying about other features holding it up. For this reason all
29+
commits need to be made to "develop" and any sent to "master" will be closed
30+
automatically. If you have multiple changes to submit, please place each
31+
change into their own branch on your fork.
32+
33+
One thing at a time: a pull request should only contain one change. That does
34+
not mean only one commit, but one change - however many commits it took. The
35+
reason for this is that if you change X and Y but send a pull request for both
36+
at the same time, we might really want X but disagree with Y, meaning we
37+
cannot merge the request. Using the Git-Flow branching model you can create
38+
new branches for both of these features and send two requests.
39+
40+
Forking
41+
=======
42+
43+
You work with a fork of the CodeIgniter4 repository. This is a copy of our repository,
44+
in your github account. You can make changes to your forked repository, while
45+
you cannot do the same with the shared one - you have to submit pull requests
46+
to it instead.
47+
48+
`Creating a fork <https://help.github.com/articles/fork-a-repo/>`_ is done through the Github website. Navigate to `our
49+
repository <https://github.com/bcit-ci/CodeIgniter4>`_,
50+
click the **Fork** button in the top-right of the page, and choose which account or
51+
organization of yours should contain that fork.
52+
53+
Cloning
54+
=======
55+
56+
You *could* work on your repository using Github's web interface, but that is
57+
awkward. Most developers will clone their repository to their local system,
58+
and work with it there.
59+
60+
On Github, navigate to your forked repository, click **Clone or download**, and
61+
copy the cloning URL shown. We will refer to this as ORIGIN_URL.
62+
63+
Clone your repository, leaving a local folder for you to work with::
64+
65+
cd ALL_PROJECTS
66+
git clone ORIGIN_URL
67+
68+
Synching
69+
========
70+
71+
Within your local repository, Git will have created an alias, **origin**, for the
72+
Github repository it is bound to. You want to create an alias for the shared
73+
repository, so that you can "synch" the two, making sure that your repository
74+
includes any other contributions that have been merged by us into the shared repo.::
75+
76+
git remote add upstream UPSTREAM_URL
77+
78+
Then synchronizing is done by pulling from us and pushing to you. This is normally
79+
done locally, so that you can resolve any merge conflicts. For instance, to
80+
synchronize **develop** branches::
81+
82+
git checkout develop
83+
git pull upstream develop
84+
git push origin develop
85+
86+
You might get merge conflicts when you pull from upstream. It is your responsibility
87+
to resolve those locally, so that you can continue collaborating with the shared
88+
repository. Basically, the shared repository is updated in the order that contributions
89+
are merged into it, not in the order that they might have been submitted.
90+
If two PRs update the same piece of code, then the first one to be merged
91+
will take precedence, even if it causes problems for other contributions.
92+
93+
It is a good idea to synchronize repositories when the shared one changes.
94+
95+
Branching Revisited
96+
===================
97+
98+
The top of this page talked about the **master** and **develop** branches.
99+
The *best practice* for your work is to create a *feature branch* locally,
100+
to hold a group of related changes (source, unit testing, documentation,
101+
change log, etc). This local branch should be named appropriately,
102+
for instance "fix/problem123" or "new/mind-reader".
103+
104+
For instance, make sure you are in the *develop* branch, and create a
105+
new feature branch, based on *develop*, for a new feature you are creating.::
106+
107+
git checkout develop
108+
git checkout -b new/mind-reader
109+
110+
Saving changes only updates your local working area.
111+
112+
Committing
113+
==========
114+
115+
Your local changes need to be *committed* to save them in your local repository.
116+
This is where `contribution signing <signing>`_ comes in.
117+
118+
You can have as many commits in a branch as you need to "get it right".
119+
For instance, to commit your work from a debugging session::
120+
121+
git add .
122+
git commit -S -m "Find and fix the broken reference problem"
123+
124+
Just make sure that your commits in a feature branch are all related.
125+
126+
If you are working on two features at a time, then you will want to switch
127+
between them to keep the contributions separate. For instance::
128+
129+
git checkout new/mind-reader
130+
// work away
131+
git add .
132+
git commit -S -m "Added adapter for abc"
133+
git checkout fix/issue-123
134+
// work away
135+
git add .
136+
git commit -S -m "Fixed problem in DEF\Something"
137+
git checkout develop
138+
139+
The last checkout makes sure that you end up in your *develop* branch as a
140+
starting point for your next session working with your repository.
141+
This is a good practice, as it is not always obvious which branch you are working in.
142+
143+
Pushing Your Branch
144+
===================
145+
146+
At some point, you will decide that your feature branch is complete, or that
147+
it could benefit from a review by fellow developers.
148+
149+
.. note::
150+
Remember to synch your local repo with the shared one before pushing!
151+
It is a lot easier to resolve conflicts at this stage.
152+
153+
Synchronize your repository::
154+
155+
git checkout develop
156+
git pull upstream develop
157+
git push origin develop
158+
159+
Bring your feature branch up to date::
160+
161+
git checkout new/mind-reader
162+
git merge develop
163+
164+
And finally push your local branch to your github repository::
165+
166+
git push origin new/mind-reader
167+
168+
Pull Requests
169+
=============
170+
171+
On Github, you propose your changes one feature branch at a time, by
172+
switching to the branch you wish to contribute, and then clicking
173+
on "New pull request".
174+
175+
Make sure the pull request is for the shared **develop** branch, or it
176+
may be rejected.
177+
178+
Make sure that the PR title is helpful for the maintainers and other developers.
179+
Add any comments appropriate, for instance asking for review.
180+
181+
.. note::
182+
If you do not provide a title for your PR, the odds of it being summarily rejected
183+
rise astronomically.
184+
185+
When your PR is submitted, a continuous integration task will be triggered,
186+
running all the unit tests as well as any other checking we have configured for it.
187+
If the unit tests fail, or if there are merge conflicts, your PR will not
188+
be mergeable until fixed.
189+
190+
Fix such changes locally, commit them properly, and then push your branch again.
191+
That will update the PR automatically, and re-run the CI tests. You don't need
192+
to raise a new PR.
193+
194+
If your PR does not follow our contribution guidelines, or is incomplete,
195+
the codebase maintainers will comment on it, pointing out what
196+
needs fixing.
197+
198+
Cleanup
199+
=======
200+
201+
If your PR is accepted and merged into the shared repository, you can delete
202+
that branch in your github repository as well as locally.

0 commit comments

Comments
 (0)